Let a mode react to a click from a real mouse

[mitchellngoodman]

Category

Configuration

Target platform

macOS

Problem or use case

I drive Neru alongside a keyboard that sends a real mouse click from a dedicated key (ZSA Voyager, but any pointing device or mouse-button key behaves the same). When I use recursive grid to place the cursor and then click with that key, the click lands correctly but the grid overlay stays up, and I have to press Escape afterwards to dismiss it.

Nothing in Neru can react to that click today. The mode event tap watches keyboard events only, so a physical button press is invisible to the active mode — there is no binding, flag, or setting that can dismiss an overlay when the user clicks with a real mouse.

The --action left_click flag covers the case where Neru performs the click itself, but not the case where the click comes from hardware that Neru does not drive.

Proposed solution

Report the physical mouse buttons to the active mode as bindable named keys — MouseLeft, MouseRight, MouseMiddle — so they can be written in a mode's hotkey table like any other key:

[recursive_grid.hotkeys]
"MouseLeft" = "idle"    # clicking anywhere closes the grid

Two properties seem necessary for this to be safe:

• Observe, never consume. The binding runs in addition to the click reaching the application underneath, so the click still does what it normally does.
• Ignore Neru's own clicks. Clicks that Neru performs (action left_click, --action left_click) must not trigger these bindings, or a binding could recurse into itself.

Being bindable rather than a boolean setting means it composes with macros and works in any mode, and it adds no new config option — which seemed preferable given that every option is a cost.

Since a global hotkey is resolved to a virtual key code and a mouse button has none, a mouse button written in the global [hotkeys] table would parse and then never fire; refusing it there with a message pointing at the mode tables avoids that silent failure.

Alternatives considered

• A boolean like recursive_grid.exit_on_external_click. Simpler to describe, but it adds a config option, only answers the one question, and cannot express right-click or middle-click, or any action other than exiting.
• Reprogramming the keyboard firmware to tap an unused key (F13) before clicking, and binding that to idle. Works without any Neru change, but the extra keystroke is then sent everywhere, including outside Neru, so it has to stay unbound in every other application.
• Doing nothing and using --action left_click. Only helps when Neru performs the click; it cannot see a click from external hardware.

Related but distinct

The existing mouse work all runs the other direction — Neru producing a click. #1102 added right/middle click and the mouse down/up/toggle bindings, and #640 asked for an action that also exits the mode, which shipped as --action exiting on completion. Both are about a click Neru performs. This asks for the input direction: a click Neru did not perform reaching the active mode.

Contribution

Yes — I have this working locally against main and will open a PR shortly. It touches the macOS event tap, the shared key vocabulary, and the config reference; just ci passes.

[mitchellngoodman]

Hi @y3owk1n I attempted a pr here #1418, but if you prefer a different approach feel free to reject it. Would love this feature though!

[y3owk1n]

@mitchellngoodman i will take a look at the proposal and the PR later, but i am sorry to say that, i am still in the mid of restructuring the codebase. You might need to do some rebasing afterwards, hopefully it wont have any conflict on your changes.

[y3owk1n]

@mitchellngoodman i am still thinking deep about this, not sure if I would really want this to be in the codebase at the moment. I read in detail on your issue above, quoting this:

I drive Neru alongside a keyboard that sends a real mouse click from a dedicated key (ZSA Voyager, but any pointing device or mouse-button key behaves the same). When I use recursive grid to place the cursor and then click with that key, the click lands correctly but the grid overlay stays up, and I have to press Escape afterwards to dismiss it.

I am also a Voyager user 🍻 . That aside, if the issue is to have to press Escape afterwards is an issue, what about this configuration?

[recursive_grid.hotkeys]
# note that `u` key is just the key that i uses often, whatever that you're using for the click, you can set them in.
"u" = "run 'action left_click' 'idle'" # or `"u" = [ "action left_click", "idle" ]` if you prefer array syntax

What it does is, it will run the action (in this case left click) and then exit the mode, without the need for you to exit it yourself. However, the downside is that, you would lose the ability to double and triple click it, so my recommendation would be bind this as a modified key instead.

[recursive_grid.hotkeys]
"u" = "action left_click" # pressing `u` doesnt exit the mode, you can press it multiple times for double or triple clicks
"Shift+U" = "run 'action left_click' 'idle'" # pressing `shift+u` instead will do a single click and quit the mode automatically

---

The main reason that i am still thinking about this is that, neru was built so that you don't have to touch a mouse at all, adding mouse specific feature seems a little bit weird to me. haha.. but i might change my mind in the future, who knows.