[Juliusolsson05]

TL;DR

Turns xterm's WebGL renderer back on by pinning the 0.20.0 beta line (the only one with the atlas-corruption fix), and locally patches a real upstream bug in that beta's core that would otherwise duplicate/drop terminal output on resize. Everything is exact-pinned, guarded by a test that fails if the patch goes missing, and documented where the next person bumping xterm will look.

Problem

• WebGL has been off since 2026-09-08 (fix: repair the regressions and dead paths introduced by the 2026-09-07/08 merges #841): stable @xterm/addon-webgl@0.19.0 corrupts its texture atlas under provider-TUI output (bug(terminal): WebGL atlas changes leave stale glyphs after scrolling #789). The fix (xterm.js #5883) exists only on the 0.20.0 beta line, which requires a beta @xterm/xterm. Staying on the DOM renderer costs every raw terminal a per-row DOM rebuild on every repaint (perf(terminal): one agent-pty-data dispatcher per window and the WebGL renderer for xterm hosts #768).
• Review of the first version of this PR found that the beta core has its own bug: resize() calls WriteBuffer.flushSync() (upstream bf7c95b6, since 6.1.0-beta.96), which re-applies chunks already parsed (duplicate output, write callbacks fired twice) and drops everything queued behind an empty write. It is known upstream (open resize() while an async parser handler is pending leaves the parser in FAIL; terminal stops rendering xtermjs/xterm.js#6154; maintainer: "resize is a sync action and may not call WriteBuffer.flushSync"); Superset patches the same bug (fix(desktop): patch xterm so a resize mid image decode cannot kill the terminal ParadevAI/Paradev#7188). It predates the atlas fix, so no beta avoids it.
• Agent Code's pane attach is exactly the trigger (replay(term, [512 KiB buffer, backlog]) then fit()): with the real terminalInputForwarder, 7/20 simulated attaches leaked terminal query replies into the agent's stdin on the unpatched beta and broke the perf(terminal): attaching an agent terminal replays 512 KB into xterm and floods stdin with query replies #745 latch for the next replay. 0/20 on 6.0.0, 0/20 patched.

What this does

1. Exact pins (a caret on a prerelease would float to a newer beta on the next lockfile refresh and move the core out from under the patch): @xterm/xterm 6.1.0-beta.304, @xterm/addon-webgl 0.20.0-beta.300 (both = VS Code's lockfile), @xterm/addon-fit 0.12.0-beta.301 (its peer range requires the new core). Lockfile changes only those three entries.
2. Local core patch — scripts/patch-xterm.mjs, run by postinstall AND at electron.vite.config.ts evaluation (so installs that skipped lifecycle scripts cannot bundle the unpatched core; the renderer also excludes @xterm/xterm from Vite's dev pre-bundle so a pre-patch cache can never be served): removes this._writeBuffer.flushSync() from resize() in both shipped bundles, restoring stable 6.0.0 resize semantics. The maintainer-endorsed narrow form rather than Superset's larger flushSync/_innerWrite rewrite (that targets an async image-decoder case we don't have; src/ registers no parser handlers). The script edits one exact string, verifies the installed version against the pin, is idempotent and self-verifying, and fails the install loudly on any other version or bundle shape. A script rather than patch-package because the bundles are minified (one 391 KB line) — a diff would be about 1.1 MB of unreviewable patch across both bundles. Its header is the documentation: the bug, the trigger, the app impact, and exactly what to do on a bump (including when upstream fixes it).
3. Guard test — xtermResizeFlushPatch.test.ts: patch present in both bundles + three deterministic cases (resize inside a write callback; empty write + resize; resize after the writer yielded), run against the real installed lib/xterm.mjs and lib/xterm.js. All 7 fail on the unpatched beta, pass patched; the three behaviours pass on 6.0.0.
4. WebGL switch on (WEBGL_RENDERER_ENABLED = true, still the one-line rollback for renderer issues — it does NOT roll back the core patch). The 0.19.0 atlas bridge is deleted.
5. Refit on renderer change: WebGL floors cell width, DOM keeps it fractional, so a context-loss fallback kept a grid wider than the pane (clipped). attachXtermWebglRenderer(term, { onRendererChange }) fires after WebGL takes over and after a real fallback; all three hosts route it into their existing ownership-gated fit.

Review rounds

Round 2 (two orchestrated reviewers: A runtime/Codex, B docs+tests/Codex; B's original Claude session hit the account spend limit and was replaced on the same brief)

• A — no correctness defect in the patch or the refit. Removing the flush is safe on beta.304: upstream's separate resize-during-write fix (#5598) is present, and nothing newer relies on resize draining the queue. Patched stress run: 650 resizes, 1,126 callbacks, each fired exactly once. It found two enforcement gaps; both were reproduced and fixed in b00fc5d1:
  • installs that skip lifecycle scripts bundled the unpatched core → electron.vite.config.ts now runs the idempotent patch at config evaluation;
  • Vite's dev pre-bundle cache is keyed on the lockfile, not file contents → the renderer excludes @xterm/xterm from optimizeDeps.
• B1 Minor: the removal procedure didn't mention the config gate or the test's source read, so following it would have caused ENOENT in dev/build and in test collection. It now lists all five pieces (18ba1932).
• B2 Minor: refit behaviour was only tested on the inline host. There are now behavioural cases for AgentTerminalLeaf and TerminalLeaf plus a non-owner "must not resize" case. They are mutation-checked: no-op wiring fails the refit cases, and a fence-bypassing callback fails the non-owner case (6bf3e648).
• B3 Minor: patch-package size corrected to about 1.1 MB across both bundles.

Round 1 (A runtime/Codex, B integration/Claude)

• A1 Critical — the core resize bug → item 2 + 3. Independently confirmed by source reading, a web/GitHub research pass (upstream timeline, VS Code stable 1.109–1.137 ship affected betas), and differential integration runs.
• A2 Important — context-loss refit → item 5.
• B1 Important — the Electron pixel harness (scripts/smoke-terminal-renderer.mjs) required --control to reproduce corruption, guaranteed to fail on the fixed addon; both modes now must render clean.
• B2–B4 Minor — header no longer claims VS Code ships addon-fit; lockfile numbers corrected; the two TerminalLeaf suites mock the renderer module. B5 (upstream-watch entry for xterm) not taken — the watcher is provider-CLI specific; the patch script's version guard is the trigger on any bump.

Linked issues

Fixes #871
Refs #768, #789, #841, xtermjs/xterm.js#6154

Verification

Local, Node 24, isolated worktree node_modules:

• Fresh npm ci --include=dev — exit 0; postinstall applied the patch to both bundles (what CI and packaging do).
• npm run typecheck — exit 0. npm run test:contract — ok.
• Guard + terminal unit suites 30/30; host renderer suites (AgentTerminalLeaf.*, TerminalLeaf.*) 36/36 at round 1; after round 2 the ownership suite is 13/13 with renderer-change refit cases for all three hosts plus a non-owner case (mutation-checked); agentTerminalFollow.system 1/1; xtermWebglRenderer.test.ts 15/15 (refit cases fail before the implementation). npm run typecheck re-run after round 2 — exit 0.
• Integration evidence (scratchpad harnesses, not committed): differential Node stress runs (6.0.0 vs beta vs patched beta), the real-forwarder attach simulation (numbers above), and upstream research.
• CI quality-gate (full suites, coverage, test:package production build) — see checks.

Before merging: manual check (tests cannot see pixels; agents don't launch the app)

0. Optional objective pre-check: node scripts/smoke-terminal-renderer.mjs and … --control — both should exit 0 (differences: [], referenceDifference: 0). Launches a throwaway Electron window, not the app.
1. Run the branch; push heavy Claude Code / Codex output in terminal view, OpenCode Terminal, and a plain shell; resize panes while output streams, switch lanes, open a new pane on a busy agent, sleep/wake.
2. Watch for garbled glyphs, repeated output after resizes, a pane that stops updating. If glyphs look wrong: copy the text — clean clipboard = renderer (set WEBGL_RENDERER_ENABLED = false); dirty = data path.

Risks / follow-ups

• We carry a local patch on a beta core until upstream fixes #6154 or ships 6.1.0 stable; the script's "WHEN THIS FAILS" section is the removal procedure.
• Move to stable @xterm/xterm 6.1.0 / @xterm/addon-webgl 0.20.0 when published — one deliberate PR.
• Note: our public PR/issue comments mentioning resize() while an async parser handler is pending leaves the parser in FAIL; terminal stops rendering xtermjs/xterm.js#6154 created an automatic cross-reference backlink on that upstream issue.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SVRSHn7c7qnBoUQo1e2X4k

[Juliusolsson05]

Merge blocked — converted to draft. Independent review (orchestrated reviewer A, runtime) found a critical regression in the pinned core beta, reproduced and independently confirmed:

• @xterm/xterm 6.1.0-beta.304 duplicates already-parsed output — and fires the first write callback twice — when the terminal resizes between write batches. Upstream commit bf7c95b6 ("Flush writes on resize", 2026-01-09) added flushSync() to resize; it ignores WriteBuffer._bufferOffset, so a partially consumed queue (heavy output exceeding the 12 ms parse budget) is re-parsed from index 0.
• Minimal repro (Node, no DOM): write FIRST whose callback exceeds the budget and schedules resize(81, 24), then write SECOND. 6.0.0 → FIRST, SECOND, callbacks 1/1. beta.304 → FIRST, FIRST, SECOND, callbacks 2/1.
• It is in core, independent of WebGL, so the renderer switch cannot roll it back. Heavy provider output + frequent pane/lane resizes is exactly this app's workload, and terminalInputForwarder's replay latch assumes exactly-once write callbacks.
• No safe beta exists: the regression (2026-01-09) predates the atlas fix #5883 (2026-05-21), so every beta that contains the WebGL fix also contains it. Later WriteBuffer.ts commits (#5912 fix, dispose cleanup, 2026-05/06) do not address the offset. A sibling issue from the same change is open upstream: resize() while an async parser handler is pending leaves the parser in FAIL; terminal stops rendering xtermjs/xterm.js#6154. The duplicate-output case does not appear to be reported upstream yet.

Second finding (Important, our code): on WebGL context loss the fallback keeps the WebGL grid (WebGL floors cell width, DOM keeps it fractional) and no host refits, so text can be clipped until the next layout change. Must be fixed before WebGL is re-enabled on any version.

main is unaffected (core 6.0.0, WebGL off). Decision on the path forward is with the user; details in #871.