[Shironex]

The flip did not happen — and shouldn't yet

Refs #430. This PR deliberately does not close it. I went to flip the macOS branch of the
renderer resolution to GPU, established the facts first, and the flip-back condition is not
met. What lands here is the corrected evidence and a sharper trigger, not a behavior change.

Nothing user-visible changes: macOS still resolves to DOM, Windows/Linux still resolve to GPU,
no dependency moves, bun.lock untouched.

What I established

Question	Answer	How
Did xtermjs#5883 merge?	Yes — 2026-05-21, commit 3e2a42e	GitHub API
Which package does it fix?	@xterm/addon-webgl, not the @xterm/xterm core	all 4 changed files are under addons/addon-webgl/src
Which released version first contains it?	None. No stable release carries it	see below
First published artifact carrying it	@xterm/addon-webgl@0.20.0-beta.219 (2026-05-21, ~1h after merge)	tarball inspection
What this repo takes	@xterm/addon-webgl@0.19.0 (stable, 2025-12-22) — predates the merge	bun.lock

The core lesson is that the fix is in the addon, not the core — so "which xterm release
contains it" is the wrong question; the addon versions independently.

• @xterm/addon-webgl has exactly three stable releases ever: 0.17.0, 0.18.0, 0.19.0
  (2025-12-22). npm dist-tags.latest is still 0.19.0. All three predate the 2026-05-21
  merge.
• The only artifacts carrying the fix are 0.20.0-beta.219 … 0.20.0-beta.291 prereleases.
• Corroborated on the git side: the merge commit is ahead_by: 848, behind_by: 0 vs. tag
  6.0.0, which is the newest tag in the repo — the fix is in no tagged release.

Verified by content, not by dates. I downloaded the tarballs and grepped for the fix's own
markers (AtlasPage.nextVersion, invalidateAtlasTextures, MERGE_RETRY_LIMIT):

version	published	markers
0.18.0	2024-04-05	absent
0.19.0 ← ours	2025-12-22	absent
0.20.0-beta.218	2026-05-12	absent (last beta before the merge)
0.20.0-beta.219	2026-05-21	present (first carrier)
0.20.0-beta.291	2026-07-27	present (latest beta)

Why I did not take the beta

0.20.0-beta.219's peerDependencies is {"@xterm/xterm": "^6.1.0-beta.220"} — and the latest
beta wants ^6.1.0-beta.292. Taking the fix today moves the whole terminal stack onto the
prerelease channel (core + every addon in lockstep), to fix a bug whose only symptom is visual,
on the platform we develop on, with no gate that can catch a regression. That trade is worse than
the DOM renderer. #430 itself set the bar at "in a released xterm the repo has taken".

What this PR changes

1. apps/web/src/lib/platform.ts — the comment above DEFAULT_TERMINAL_WEBGL asserted the
   fix PR was "unmerged". That was true when written and is now false, which is the kind of stale
   claim that gets a default flipped on a bad premise later. Replaced with the actual status and
   a checkable trigger (npm view @xterm/addon-webgl version).
2. docs/research/2026-07-10-terminal-build-spec.md (decision 7) — same stale "fix PR
   unmerged" note, corrected in place with a dated re-check, per the register's rule that no
   living doc keeps contradictory prose.
3. docs/decisions/INDEX.md — D-010 amended in place (still ✅ active, original text intact):
   records that the condition was checked and not met, with the evidence, and restates the
   trigger as a stable @xterm/addon-webgl ≥ 0.20.0 carrying #5883 rather than "#5816 is
   closed". #5816 is still open, but issue state was always the wrong signal — an issue routinely
   outlives its fix, and here the fix landed while the issue stayed open. Release state is the
   fact that actually gates us.

Tri-state semantics: unchanged

Nothing touched resolveTerminalWebgl, Settings.terminalWebglEnabled, the Rust
Settings/SettingsPatch shape, or the camelCase pinning tests. stored ?? DEFAULT_TERMINAL_WEBGL
still means Some(false) (explicit opt-out) is returned verbatim and can never be flipped on by
a default change — only null consults the platform default.
apps/web/src/lib/platform.test.tsx pins all four cases (true / false / null / undefined).

The escape hatch (unchanged, and where it lives)

Settings → Terminal → "GPU rendering (WebGL)" —
apps/web/src/components/settings/settings-terminal-cards.tsx. Toggling it writes an explicit
true/false that outranks the platform default forever after. Independently,
terminal-webgl.ts wires the addon's onContextLoss to dispose the addon (xterm reverts to DOM)
and raise a toast, so even an explicit opt-in degrades to DOM rather than to a blank pane.

Deferred, and now on the record: the WebKit context cap

#430 also parks an LRU WebGL context pool for WebKit's ~16-live-context cap. Since macOS stays on
DOM, it does not become urgent from this PR — macOS is the WebKit target, and the pool is
load-bearing only once macOS resolves to GPU. It does not need its own ticket today, but it is
a hard prerequisite of the eventual flip, not a follow-up to it: with the tab cap at 8 terminals
plus any other GL surface, flipping macOS to GPU without pooling walks toward a cap where WebKit
force-loses the oldest context unrecoverably. Whoever executes the flip should land the pool in
the same change. #430 stays open and carries both.

Verification

No behavior changed, so there is nothing here for a human to look at. The visual check #430 calls
for is not owed on this PR — it is owed on the future PR that actually flips the default, and
that PR still cannot be proven green by any gate in this repo: WebGL corruption is a rendering
artifact, headless chromium has no reliable WebGL context, and there are no pixel tests for xterm.

Gates run locally, all green: lint · typecheck · tsc -b apps/web · lint:meta ·
codegen:check · test:web (514 files / 2937 tests, both vitest projects) · test:node
(2022 tests) · test:plugin · audit (5 pre-existing tolerated advisories, no new
suppressions). Rust untouched; codegen:check's cargo legs still ran and
git diff --exit-code -- apps/web/src/lib/generated is clean.