Files

T

retoor 29c489e27a Standalone tai.py: native TUI framework, grouped classes, full suite green

- In-tai.py TUI framework (panels, compositor, z-layers, mouse, focus,
  VT screen, pty sub-terminals, widgets, animation) plus /demo, --demo,
  --demo-shot, tui.md docs, and research/tui-framework-design archive
- Focus safety: Tab/Shift+Tab always cycle, auto-focus prefers
  non-terminals, dialogs restore previous focus on close
- Native Consts/Install/Sandbox/Opencode/SysInfo classes in tai.py;
  module functions delegate so live patches apply; fixes 19 failures
- Retargeted 4 test patches to the real tai.* seams (assertions unchanged)
- Deleted tai_pkg/; tai.py is standalone stdlib-only (bare copy imports)
- AGENTS.md/README.md updated to the standalone architecture
- test_tai.py 320/320 OK, test_seal.py 16/16 OK

2026-10-10 23:45:12 +02:00

2.6 KiB

Raw Blame History

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.

2.6 KiB Raw Blame History