Repository navigation
Description
Summary
Mouse capture can stop working in a mouse-enabled TUI after wmux remounts its terminal during a split-tree/layout restructure. The PTY and TUI remain alive, but the replacement xterm instance no longer uses the SGR mouse encoding requested by the application.
Observed with herdr (mouse_capture = true) on Windows, but the mechanism applies to any TUI that enables DEC mouse tracking plus SGR encoding, such as tmux/vim-style applications.
Symptoms
- mouse clicks and drags previously work in the TUI
- after an intermittent terminal remount, clicks no longer reach the application correctly
- wheel behavior may continue because wmux forwards it through a separate custom SGR path
- if a mouse gesture spans disposal, DevTools repeatedly reports:
Uncaught TypeError: Cannot read properties of undefined (reading 'dimensions')
at get dimensions
at getMouseReportCoords
at HTMLDocument.mouseup / HTMLDocument.mousedrag
Root cause
wmux snapshots the old terminal with:
serializeAddon.serialize({ excludeAltBuffer: true })and writes that snapshot into the replacement terminal. Modes are included, but xterm's SerializeAddon serializes only the mouse tracking protocol (?9, ?1000, ?1002, or ?1003). It does not serialize the active mouse encoding (?1006 SGR or ?1016 SGR pixels).
A controlled test using the same xterm 6.0.0 and SerializeAddon versions shows:
{
"beforeProtocol": "DRAG",
"beforeEncoding": "SGR",
"snapshotTail": "\\u001b[?1002h",
"afterProtocol": "DRAG",
"afterEncoding": "DEFAULT",
"publicMode": "drag"
}The TUI still believes its earlier DECSET 1006 is active and does not necessarily resend it after SIGWINCH/remount, while the replacement xterm sends legacy/default mouse reports.
wmux already tracks 1000/1002/1003/1006 output in surfaceMouseEnabled, but collapses them into one boolean used by its custom wheel handler. That handler always emits SGR reports, explaining why wheel behavior can survive while xterm-owned clicks do not.
Related xterm issue
The repeated RenderService.dimensions exception is a second remount/disposal problem in xterm 6.0.0: transient document-level mouse listeners can survive Terminal.dispose() when a gesture spans teardown.
- Document-level mouse listeners survive Terminal.dispose() in 6.0.0, throwing TypeError from RenderService.dimensions on the next mouseup xtermjs/xterm.js#6070 documents the exact exception and reproduction
- Use current document for mouse listeners xtermjs/xterm.js#6019 is merged on master and makes those transient listeners disposable, but the fix is not in stable 6.0.0
That upstream fix removes the stale-listener exception, but it does not restore mouse encoding state into a completely new Terminal, so wmux still needs to address the remount state loss.
Expected behavior
A replacement xterm instance should preserve the complete active mouse state expected by the still-running PTY application:
- tracking protocol (
9/1000/1002/1003) - coordinate encoding (
1006/1016)
Click, drag, and wheel behavior should remain unchanged after pane/layout remounts.
Suggested direction
- track mouse protocol and encoding separately per surface instead of one boolean
- replay the exact active modes into the replacement xterm after restoring the serialized buffer
- cover combined/multiple DECSET and DECRST sequences, not only one simple escape per PTY data chunk
- ensure teardown cannot leave xterm 6.0 transient document listeners active, or consume the upstream fix when it reaches a release
Verification criteria
- Start a TUI that enables
?1002hand?1006h. - Confirm clicks, drags, and wheel reports work.
- Trigger a split-tree restructure that remounts the terminal while retaining the PTY.
- Confirm the replacement terminal remains in
DRAG+SGRmode. - Confirm clicks, drags, and wheel reports still work and no
RenderService.dimensionsexceptions occur.
Activity
fix(terminal): keep SGR mouse encoding across a remount (#164)
amirlehmam commentedon Aug 14, 2026
Fixed in 1.0.0. Your root cause was exact, including the part that explains the symptom nobody could make sense of.
The controlled capture is what made this diagnosable
{ "beforeProtocol": "DRAG", "beforeEncoding": "SGR", "snapshotTail": "\\^[[?1002h", "afterProtocol": "DRAG", "afterEncoding": "DEFAULT" }SerializeAddonemits the tracking protocol and not the coordinate encoding. That single asymmetry produces a replacement terminal that is tracking drags correctly and reporting them in a format the application isn't decoding — and the application will never correct it, because from its side nothing happened and there is no reason to re-send aDECSETit already sent.And your observation about the wheel is the tell I'd have chased for a long time otherwise: wmux's wheel handler writes SGR reports itself and never consulted xterm's encoding at all. So the wheel kept working while xterm-owned clicks broke, which reads like a click-handling bug and is nothing of the sort.
What shipped
Mouse modes are tracked per surface, protocol and encoding separately (
src/renderer/utils/mouse-modes.ts), and the active modes are replayed into the replacement terminal after the buffer snapshot. The replay emits every active mode rather than just the effective one, so the new terminal's flags match the original rather than merely behaving the same today — a laterDECRSTfrom the application then lands on the state it expects.You called the single boolean out as the problem and it was, in a more direct way than "it loses information": the encoding had nowhere to live. There was no field to restore.
Three parsing bugs fell out of the same rewrite, all of which your "cover combined/multiple DECSET and DECRST sequences, not only one simple escape per PTY data chunk" predicted:
ESC[?1002;1006h— the usual spellingelse ifsaw the first and stoppedDECRSTof one protocol while another is liveModes are now independent flags per category with the effective mode derived by precedence, which is what real terminals do. 14 tests, including a round-trip and the DRAG+SGR case straight from your capture.
They're also dropped on PTY exit — otherwise the next application on that surface, quite possibly a plain shell that never asked, would have tracking replayed into it.
The second problem — mitigated here, not waiting on upstream
You were right that xtermjs/xterm.js#6019 wouldn't be enough even once it ships: it makes the transient listeners disposable, but it does not restore mode state into a brand-new
Terminal. Those are two separate defects that happen to fire together.For the
RenderService.dimensionsexception specifically, wmux now synthesises amouseupon the document immediately beforeterminal.dispose(). xterm 6.0.0 attaches its drag listeners to the document on mousedown and removes them on mouseup, and they aren't in the terminal's disposable store — so a gesture spanning a remount outlives disposal and every subsequent event runsgetMouseReportCoordsagainst a deadRenderService. Letting xterm's own handler run while the terminal is still alive is the same teardown the user would have triggered by releasing the button, and it costs nothing when no gesture is in flight. The comment says it can be removed once #6019 reaches a stable release.What I'd still like from you
The verification criteria you listed are the right ones, and steps 3–5 are the part I can only partially exercise here — I can force a split-tree restructure, but not with herdr's exact mode sequence and not with a gesture spanning the remount reliably. If you're able to run your controlled test against 1.0.0 and post the
afterblock, that would close it properly:{ "afterProtocol": "?", "afterEncoding": "?" }SGRis the answer I'm expecting. If it comes backDEFAULTagain then the replay is landing before something that resets it, and the ordering relative to the snapshot write is the first thing I'd look at.Leaving this open until you've had a chance to check rather than closing it on my own testing. Two excellent reports in one day — thank you.
LevSky22 commentedon Aug 15, 2026
Verified fixed in the official wmux 1.1.1 installer on Windows 11 Pro 10.0.26200.
Controlled raw mouse-protocol test:
{ "beforeProtocol": "DRAG", "beforeEncoding": "SGR", "afterProtocol": "DRAG", "afterEncoding": "SGR" }CSI ? 1002 ; 1006 hsequence.ESC [ </ hex1b5b3c), 0 DEFAULT reports.0), held-button motion (32), and release (0 ... m) were all still SGR; 3 SGR reports, 0 DEFAULT reports.Real application test:
getMouseReportCoords,RenderService.dimensions, orCannot read properties of undefined (reading dimensions)errors.The disposable Herdr session and wmux workspace were removed after testing; the original agent session was left untouched. Thanks — this closes the loop on the exact reproduction from the report.
amirlehmam commentedon Aug 16, 2026
Closing on your verification rather than on my own — which is why I left it open in the first place.
What you settled
{ "beforeProtocol": "DRAG", "beforeEncoding": "SGR", "afterProtocol": "DRAG", "afterEncoding": "SGR" }SGRwas the answer I said I was expecting, and the useful part is that you didn't stop there. Three things in your run cover the parts I explicitly could not exercise here:CSI ? 1002 ; 1006 h, which is what real applications send and what the old single-regex parser silently half-readmouseupbeforedispose()exists for, and an empty DevTools console afterwards is the evidence that it did its job rather than merely not being reached.Forcing the restructure by collapsing an adjacent pane while the button was down is a better reproduction than the one I was running. Mine restructured the tree but never with a gesture genuinely in flight.
The Herdr 0.8.0 + Codex pass on top of the raw protocol test is what makes it a fix rather than a passing assertion.
Where it stands now
Verified on 1.1.1, and unchanged in 1.2.0 (out now) — nothing in this release touches
mouse-modes.tsor the terminal remount path.Two notes for anyone finding this later:
RenderService.dimensionsmitigation is deliberately temporary. xtermjs/xterm.js#6019 makes the transient document listeners disposable, and when it reaches a stable release the syntheticmouseupshould come out. The comment in the source says so.Terminal. Two defects that fire together.Thank you for coming back to close the loop, and for tearing down the disposable session afterwards. Reports that end with a measurement are rare; ones that end with a measurement and a cleaned-up machine are rarer.
fix(terminal): restore a usable pane when a child dies mid-session (#175
feat(terminal): keep each surface's xterm alive across split-tree rem…