ht icon indicating copy to clipboard operation
ht copied to clipboard

Add mouse support for TUI interaction

Open io41 opened this issue 2 months ago • 0 comments

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 mouse command to STDIN API supporting:
  • Event types: press, release, drag, and click (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.

io41 avatar Nov 13 '25 12:11 io41