53 lines
2.6 KiB
Markdown
53 lines
2.6 KiB
Markdown
|
# Xterm Mouse Protocols - Technical Reference (xterm-mouse)
|
||
|
|
|
||
|
|
## Metadata
|
||
|
|
|
||
|
|
| Field | Value |
|
||
|
|
|---|---|
|
||
|
|
| Institute | Molodetz Institute — Research & Retrieval Division |
|
||
|
|
| Subject | tui-framework-design |
|
||
|
|
| Document type | Source Dossier |
|
||
|
|
| Tier | 1 |
|
||
|
|
| Source title | Xterm Mouse Protocols - Technical Reference |
|
||
|
|
| Source URL | https://raw.githubusercontent.com/neiropacks/xterm-mouse/HEAD/docs/PROTOCOLS.md |
|
||
|
|
| Source publisher / author | neiropacks (xterm-mouse library) |
|
||
|
|
| Source type | other (library protocol reference) |
|
||
|
|
| Source date (published) | Unknown — not stated |
|
||
|
|
| Date researched | 2026-10-10 |
|
||
|
|
| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
|
||
|
|
| Research method | direct page fetch |
|
||
|
|
| Confidence | High |
|
||
|
|
| Status | Active |
|
||
|
|
|
||
|
|
## Summary
|
||
|
|
|
||
|
|
A precise reference for xterm mouse tracking: enable modes 1000 (press), 1002 (drag), 1003 (any motion), and 1006 (SGR extended encoding); the SGR report format `ESC [ < b ; x ; y M/m` with 1-indexed coordinates; button codes including wheel (64-67); modifier bits (shift 4, alt 8, ctrl 16); `M` = press, `m` = release.
|
||
|
|
|
||
|
|
## Key findings
|
||
|
|
|
||
|
|
- Enable stack: `?1000h` + `?1002h` + `?1003h` + `?1006h` (disable with `l`); 1006 switches coordinate encoding to SGR while 1000/1002/1003 select which motions report.
|
||
|
|
- SGR report bytes: `0x1b 0x5b 0x3c [button] 0x3b [x] 0x3b [y] 0x4d/0x6d`; coordinates are 1-indexed integers (no 223-cell ceiling, unlike legacy X10 encoding).
|
||
|
|
- Button codes: 0 left, 1 middle, 2 right, 3 none (release with `m`), 64 wheel-up, 65 wheel-down, 66/67 horizontal wheel, 128/129 browser back/forward.
|
||
|
|
- Modifier bits OR into the button code: shift 4, alt 8, ctrl 16.
|
||
|
|
- Parser strategy used by the library: enable everything, auto-detect SGR vs legacy format per report.
|
||
|
|
|
||
|
|
## Pros / strengths
|
||
|
|
|
||
|
|
- Parse-ready tables (byte layout, button codes, modifier bits) with zero ambiguity; matches the xterm standard behaviorally.
|
||
|
|
|
||
|
|
## Cons / limitations / caveats
|
||
|
|
|
||
|
|
- Secondary source (a TS library's doc), not xterm's own ctlseqs; TS-centric framing.
|
||
|
|
- Recommends enabling all modes including 1003 (any-motion), which floods the input stream — fine for that library, wrong default for tai (motion events every cell of movement).
|
||
|
|
|
||
|
|
## Relevance to tai
|
||
|
|
|
||
|
|
- Exact spec for tai's mouse parser: enable `?1000h` + `?1006h` only in v1 (clicks + wheel, no motion flood), parse SGR reports, map to Click/Scroll events with modifiers.
|
||
|
|
- Caveat carried into the plan: some terminals (notably Terminal.app per a companion source) never negotiate 1006, so the parser must also accept legacy `ESC[M bxy` reports as fallback.
|
||
|
|
|
||
|
|
## Changelog
|
||
|
|
|
||
|
|
| Date | Change |
|
||
|
|
|---|---|
|
||
|
|
| 2026-10-10 | Initial dossier created. |
|