Skip to content

bug(terminal): SGR mouse encoding is lost after terminal remount #164

Closed

Description

@LevSky22

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.

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

  1. Start a TUI that enables ?1002h and ?1006h.
  2. Confirm clicks, drags, and wheel reports work.
  3. Trigger a split-tree restructure that remounts the terminal while retaining the PTY.
  4. Confirm the replacement terminal remains in DRAG + SGR mode.
  5. Confirm clicks, drags, and wheel reports still work and no RenderService.dimensions exceptions occur.

Activity

  1. amirlehmam commented on Aug 14, 2026

    @amirlehmam
    Owner

    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" }

    SerializeAddon emits 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 a DECSET it 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 later DECRST from 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:

    what old behaviour
    ESC[?1002;1006h — the usual spelling matched once, registered one mode, dropped the other
    enable and disable in one chunk else if saw the first and stopped
    DECRST of one protocol while another is live collapsed to "mouse off" and told the wheel handler a mouse-tracking app was a plain shell

    Modes 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.dimensions exception specifically, wmux now synthesises a mouseup on the document immediately before terminal.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 runs getMouseReportCoords against a dead RenderService. 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 after block, that would close it properly:

    { "afterProtocol": "?", "afterEncoding": "?" }

    SGR is the answer I'm expecting. If it comes back DEFAULT again 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.

  2. LevSky22 commented on Aug 15, 2026

    @LevSky22
    ContributorAuthor

    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" }
    • The probe enabled the usual combined CSI ? 1002 ; 1006 h sequence.
    • Before remount: 34 SGR reports (ESC [ < / hex 1b5b3c), 0 DEFAULT reports.
    • I forced a split-tree restructure by closing an adjacent wmux pane while the left button was held across the remount.
    • After remount: press (0), held-button motion (32), and release (0 ... m) were all still SGR; 3 SGR reports, 0 DEFAULT reports.

    Real application test:

    • Attached an isolated named Herdr 0.8.0 session and opened Codex inside it.
    • Herdr and Codex click, drag, and wheel input worked before and after the same adjacent-pane collapse/remount.
    • A mouse gesture spanning the remount did not poison later input.
    • DevTools Console remained empty after the test: no getMouseReportCoords, RenderService.dimensions, or Cannot 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.

  3. amirlehmam commented on Aug 16, 2026

    @amirlehmam
    Owner

    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" }

    SGR was 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:

    • the combined spelling — CSI ? 1002 ; 1006 h, which is what real applications send and what the old single-regex parser silently half-read
    • 34 SGR / 0 DEFAULT before, 3 SGR / 0 DEFAULT after — a count, not an impression. A replay that landed but was then reset would still show some DEFAULT reports.
    • the gesture held across the remount — press, held-button motion, release, all still SGR. That is the case the synthetic mouseup before dispose() 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.ts or the terminal remount path.

    Two notes for anyone finding this later:

    • The RenderService.dimensions mitigation is deliberately temporary. xtermjs/xterm.js#6019 makes the transient document listeners disposable, and when it reaches a stable release the synthetic mouseup should come out. The comment in the source says so.
    • The upstream fix would not have been sufficient on its own, which you called correctly in the original report. It removes the stale-listener exception; it does not restore mode state into a brand-new 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions