Skip to content

fix(serialize): preserve the mouse encoding mode - #6329

Open
lmdc45 wants to merge 1 commit into
xtermjs:masterfrom
lmdc45:fix/serialize-mouse-modes
Open

lmdc45 wants to merge 1 commit into
xtermjs:masterfrom
lmdc45:fix/serialize-mouse-modes

Conversation

@lmdc45

@lmdc45 lmdc45 commented Nov 16, 2026 •

Copy link
Copy Markdown

Problem

SerializeAddon serializes the mouse tracking mode (?1000/?1002/?1003) but not the mouse encoding (?1006 SGR / ?1016 SGR-Pixels). Replaying a serialized terminal that used SGR mouse reporting therefore re-enables tracking with the default single-byte encoding: the application receives X10-style bytes instead of SGR sequences, and mouse input breaks until the application re-asserts ?1006 itself.

This is observable in VS Code's persistent terminal replay (window reload): the replayed TUI gets ?1002h back but never ?1006h. From the review of microsoft/vscode#326121:

Also it's not preserving the mouse encoding mode (?1006), which pretty much breaks mouse in the majority of programs that use SGR mouse [...] the right fix is probably to fix this via a pull request to xterm.js so the whole ecosystem benefits.

Change

  • IModes.mouseEncodingMode ('default' | 'sgr' | 'sgr-pixels') — new readonly field on the public modes API, mirroring the existing mouseTrackingMode shape, wired through both the browser and headless Terminal implementations from MouseStateService.activeEncoding, and declared in typings/xterm.d.ts and typings/xterm-headless.d.ts.
  • Serialization now emits the encoding when it is not the default (?1006h / ?1016h), after the tracking mode — the same skip-when-default convention every other mode in _serializeModes follows.

The three-value union is complete: ?1005/?1015 (UTF-8/urxvt encodings) are unimplemented in InputHandler (only debug-logged; DECRQM reports them as permanently reset), so activeEncoding can only ever be DEFAULT/SGR/SGR_PIXELS.

Consumers that replay into a context where the process owning the mouse modes is gone (e.g. VS Code replays a persistent terminal after a full-screen TUI child exited without resetting modes) can strip the mouse modes by appending the DECRSTs themselves — modes are serialized at the end of the output, so a trailing \x1b[?1000l\x1b[?1006l… reliably lands after them. No new option is needed for that.

Tests

  • Unit (addons/addon-serialize/src/SerializeAddon.test.ts): SGR and SGR-pixels emitted; default encoding omitted; nothing emitted after the encoding is reset (?1006h then ?1006l); round-trip replay restores mouseTrackingMode: 'drag' + mouseEncodingMode: 'sgr', and a SGR-pixels round-trip restores sgr-pixels.
  • Integration (addons/addon-serialize/test/SerializeAddon.test.ts): same coverage through the browser terminal.
  • Headless (src/headless/public/Terminal.test.ts): modes.mouseEncodingMode set/reset by ?1006h/?1016h/DECRST, and the defaults deep-equal updated.

Gates: npm run test-unit (2452 passing), npm run lint, npm run lint-api — all clean.

@lmdc45
lmdc45 force-pushed the fix/serialize-mouse-modes branch from 63d8f70 to 2b4b7cb Compare November 16, 2026 06:16
@lmdc45 lmdc45 changed the title fix(serialize): preserve mouse encoding mode, add excludeMouseModes option fix(serialize): preserve the mouse encoding mode Nov 16, 2026
SerializeAddon re-emitted mouse tracking (?9/?1000/?1002/?1003) but never
the encoding (?1006 SGR / ?1016 SGR-pixels), so a serialized+replayed
terminal reported mouse in the legacy single-byte encoding. Expose
modes.mouseEncodingMode (browser + headless) and serialize it when
non-default; consumers that must drop mouse modes can append DECRSTs
after the replay since modes serialize last.

Tests: unit (SGR, SGR-pixels, default-omitted, reset-noop, both
round-trips), integration exact-string cases, headless getter +
defaults, browser Playwright defaults key + per-mode h/l toggles.
Mode tests sit in IModes-alphabetical order in every suite.
@lmdc45
lmdc45 force-pushed the fix/serialize-mouse-modes branch from 2b4b7cb to ea59ce9 Compare November 16, 2026 09:03
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.

1 participant