Add mouse support for TUI interaction
Summary
Implements mouse event support for the headless terminal, enabling programmatic interaction with mouse-enabled TUI applications via the JSON STDIN API.
Addresses some of #2
Motivation
I need mouse support to use ht for integration testing of TUI applications. Being able to
programmatically send mouse events (clicks, drags, scrolling) is essential for comprehensive
testing of interactive terminal applications.
Changes
- Added
mousecommand to STDIN API supporting: - Event types:
press,release,drag, andclick(convenience shorthand) - Mouse buttons:
left,middle,right,wheel_up,wheel_down - Modifier keys:
shift,alt,control - 1-indexed coordinate system matching terminal conventions
- Implemented SGR extended mouse protocol (
\x1b[<format) for compatibility with modern TUI apps - Added coordinate validation with warnings when coordinates exceed terminal bounds
- Comprehensive test coverage for all event types, buttons, and edge cases
- Updated README with detailed documentation and examples
Example Usage
{ "type": "mouse", "event": "click", "button": "left", "row": 10, "col": 25 }
{ "type": "mouse", "event": "drag", "button": "left", "row": 12, "col": 30 }
{ "type": "mouse", "event": "press", "button": "right", "row": 5, "col": 15, "control": true
}
Caveats
I should note that this PR is somewhat "vibe-coded" - I'm not deeply familiar with Rust, so there may be idioms or patterns I've missed that would improve the implementation. I'd appreciate any feedback on code quality, error handling, or areas that could be more idiomatic. Happy to iterate on the implementation.
Testing
Manually tested click events, using rlwrap with a mouse-enabled TUI application. All unit
tests pass.