Skip to content

Release a terminal's WebGL context on detach - #224

Merged
nthomsencph merged 7 commits into
mainfrom
fix/206-webgl-context-leak
Nov 9, 2026
Merged

nthomsencph merged 7 commits into
mainfrom
fix/206-webgl-context-leak

Conversation

@nthomsencph

@nthomsencph nthomsencph commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

What was wrong

Every Claude terminal loaded a WebglAddon on first attach and kept it until the session was disposed. Chromium allows about 16 active WebGL contexts per renderer and force-loses the oldest past that. onContextLoss reloaded the addon at once, which pushed another terminal over the cap, so with 17+ viewed sessions the losses kept rotating and the terminal on screen blanked about every 15 s.

What changed

  • The WebGL addon stays on the most recently attached terminals, 8 by default. Attaching makes a terminal the most recent and loads the addon if it has none. Past the limit, the least recently attached terminal that isn't on screen is released. Detach alone keeps the addon, so switching between a handful of tasks never rebuilds a context.
  • The limit is a setting: Settings → Appearance → "Terminals kept ready" (under the terminal font), a 2–14 slider (14 leaves room under Chromium's ~16 for the main pane plus the attach modal). It applies at once, and lowering it releases the least recent off-screen terminals right away. It adds a Slider primitive in ui/ (shadcn's, on @radix-ui/react-slider).
  • Releasing calls WEBGL_lose_context after dispose(), so the context is freed at once instead of at GC. Dispose releases too.
  • A context lost while the terminal is detached isn't reloaded until the next attach. A loss from an addon that was already released is ignored.
  • 3 losses within 60 s keep that terminal on xterm's DOM renderer for the rest of its life, so a loss can't loop.
  • The logic lives in WebglLifecycle.ts: a pure eviction pick, a recency pool shared by all terminals with a live limit, and a per-terminal lifecycle. All of it is tested in node with a stub addon; the setting's default and 2–14 clamping have store tests.
  • Shell-only and Linux terminals still use the DOM renderer, as before.

Verification

  • pnpm type-check, pnpm lint (0 errors) and pnpm test pass.
  • It still needs a manual check: open 17+ Claude sessions, switch through them, and confirm no sad face, no Too many active WebGL contexts warning in DevTools, and that a re-shown terminal draws correctly with its scroll position kept. Also check the slider in Settings.

Fixes #206

🤖 Generated with Claude Code

Every viewed Claude terminal kept its WebglAddon until dispose, and
onContextLoss reloaded at once. Past Chromium's ~16-context cap each
reload force-lost another terminal's context, so losses rotated through
the terminals and the one on screen blanked every ~15 s.

Only attached terminals now hold a context: detach() releases the addon
and attach() loads it again. A loss on a detached terminal waits for the
next attach, and 3 losses within 60 s keep that terminal on xterm's DOM
renderer so a loss can never loop.

Fixes #206

Claude goes brr.. via Dash
WebglAddon.dispose() only drops its canvas, so a released context stayed
counted toward Chromium's cap until GC. Grab the addon's context before
dispose and call WEBGL_lose_context after it, once the addon's own
context-lost listener is gone.

Move the addon's load/release/loss handling into WebglLifecycle so it can
be tested in node with a stub addon: release on detach, no reload while
detached, a stale addon's loss ignored, reload on attach, fallback.

Refs #206

Claude goes brr.. via Dash
Claude goes brr.. via Dash
Releasing the context on every detach rebuilt it on each switch back,
with a possible flicker and a new texture atlas. A pool shared by all
terminals now keeps the addon on the 8 most recently attached ones and
releases the least recent detached holder past that. Detach alone keeps
the addon; dispose releases it and leaves the pool. Deferred reload,
stale-loss guard and the 3-in-60s DOM fallback are unchanged.

Refs #206

Claude goes brr.. via Dash
"Terminals kept ready" in Settings > Appearance sets how many recent
terminals keep their WebGL renderer: a 2-14 slider, default 8 (14 stays
under Chromium's ~16 with room for the main pane and the attach modal).
It applies at once; lowering it releases the least recent off-screen
terminals right away. Adds a Slider primitive on @radix-ui/react-slider.

Refs #206

Claude goes brr.. via Dash
Dragging 8 to 2 and back released six terminals on the way. The shown
number now follows the drag from local state, and the setting is saved
and applied only on Radix's onValueCommit.

Refs #206

Claude goes brr.. via Dash
Drop the setter override and the one-use clampedInt codec; the inline
codec parses with parseFloat so an empty stored value falls back to 8.

Refs #206

Claude goes brr.. via Dash
@nthomsencph
nthomsencph merged commit e3585ba into main Nov 9, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Terminals keep losing their WebGL context when more than ~16 Claude sessions are open (sad face every ~15 s)

1 participant