Skip to content

Conversation

@io41
Copy link

@io41 io41 commented Nov 13, 2025

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.

Tim Kersten and others added 2 commits November 9, 2025 16:25
Useful for integration testing
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