y3owk1n/neru v1.50.0

on GitHub

1.50.0 (2026-08-04)

Overview

Two big themes this release: actions become composable — sequences (neru run), named macros with arguments, failure control, named cursor slots, mouse-button hold/toggle, and neru status --json make Neru properly scriptable — and Linux grows up, with Wayland hints, multi-monitor parity, event-driven per-app config, and dramatically faster hint activation. macOS gets two long-standing memory leaks fixed and correct cursor behavior under Accessibility Zoom. And hints.clickable_roles now speaks one cross-platform vocabulary, so a single config finally works on all three platforms.

Migration Guide

hints.clickable_roles is now platform-neutral (breaking if customized)
Roles are now written as semantic names — button, link, text_field — and resolved to each platform's native vocabulary at config load. Bare native names no longer validate:

hints.clickable_roles: unknown role "AXButton": use "button"

Edit the list once — switch to semantic names, or keep exact native roles with a platform prefix ("ax:AXButton", "atspi:push button", "uia:Custom"). Prefixed entries for other platforms are ignored, not rejected, so the file stays portable. Configs that never customized clickable_roles are unaffected. Run the new neru roles command to see the vocabulary and how each entry resolves on your machine.

Config validation now reaches everywhere execution does
monitor_select bindings, the Mission Control hooks, and steps nested inside a run or --on-exit previously accepted any string. They are now validated at load, so a config carrying a silently-broken step there will be reported as invalid.

mouse_down / mouse_up are deprecated (still work)
Superseded by action left_click --state down / --state up, which works for the right and middle buttons too. Existing configs keep working; the CLI prints a deprecation warning.

Actions, Sequences & Macros

• neru run <step> [step...] — run several steps in order as one unit, using the same grammar as hotkey bindings; sequences now behave identically everywhere they're written
• --bail-on-error — mark a step fatal, so ["action left_click --bail-on-error", "idle"] only exits the mode when the click actually landed
• [macros] — named, reusable action sequences with positional arguments, invocable from any binding, --on-exit, neru run, or the new neru macro command. Validated at config load, so a typo fails config validate instead of making a key silently do nothing:

  [macros]
  click_and_exit = ["action left_click --bail-on-error", "idle"]
  
  [hints.hotkeys]
  "Enter" = "macro click_and_exit"

• Named cursor marks — save_cursor_pos / restore_cursor_pos take --slot <name>, so a macro that saves the cursor can't clobber its caller's saved position
• --on-exit on modes — run a sequence after the mode's --action is fulfilled (never on manual escape)
• Hold, release, and toggle any mouse button — --state down / --state up / --toggle on the click actions makes right-drag and middle-drag bindable for the first time; any held button is released on idle, so a drag never sticks
• move_cell — nudge the grid/recursive-grid selection to a neighbouring cell at the current layer instead of backspacing out and re-picking; ships unbound, arrow keys are the natural choice
• Held-key acceleration — optional [held_repeat] ramp scales --dx/--dy up while a key is held

Configuration & CLI

• neru status --json — machine-readable status, replacing grep/awk over display output; the toggles also gain --state on|off|toggle and report their state
• neru roles — list the semantic role vocabulary and how it resolves on this platform; --explain covers your loaded config
• F13–F24 now work in bindings and action feed on Linux and Windows
• neru config reload reports invalid configs immediately instead of timing out behind a modal alert

macOS

• Accurate cursor under Accessibility Zoom — while zoomed, every cursor-driven feature landed hundreds of points off target; events now enter above the zoom transform, and the magnified region pans to keep the cursor visible
• Two memory leaks fixed (the long tail of #1030): CGEventTap Mach ports are invalidated before release, and the accessibility priming walk no longer leaks its entire AX traversal on every focus change. Space changes also skip the expensive WindowServer reattach while the overlay is healthy

Linux

• Hints mode on Wayland (wlroots/KDE) via AT-SPI, with per-app config switching on focus change
• Multi-monitor parity with macOS on X11 and wlroots/KWin — enumeration, per-monitor overlays, HiDPI/fractional scaling, hotplug, monitor_select, move_monitor — and overlays now render on the selected monitor instead of always the leftmost one
• Hint activation is dramatically faster — a single AT-SPI Collection query (~5–15×) and compositor-based focus resolution bring activation on busy sessions from 1.5–3s to under 100ms; failures now surface as clear errors instead of silently showing nothing
• Per-app config applies instantly — focused-app changes are event-driven instead of polled
• Smooth cursor animation, mouse action indicator, and hint arrows on X11 and Wayland — at parity with macOS
• Modifier passthrough on Wayland evdev — unbound Ctrl/Alt/Cmd shortcuts reach the focused app while a mode is active
• action feed through uinput when /dev/uinput is writable — works uniformly across X11, wlroots, and KWin
• XDG base directory variables honored for config, data, and logs

Windows

• The full UI Automation control-type range is recognized for hints, so older Win32/WinForms apps can be hinted for the first time
• neru config init no longer writes a config that fails validation (exec_shell pinned a Unix path over the cmd.exe default)

Internals

A large contributor-experience sweep also landed: one package per platform with guardrail tests, compiler-enforced locking in the mode handler, a single shared rendering implementation for both Linux overlay backends, rewritten CLI/config references, and a just ci recipe that mirrors CI exactly.

Features

• action: add --bail-on-error to stop a sequence at a failure (#1140) (02c01da)
• action: add --slot for named cursor marks (#1145) (ce5d664)
• action: add move_cell for same-layer grid navigation (#1138) (5abc492)
• action: add run for ordered action sequences (#1139) (224b1ed)
• action: hold, release, and toggle any mouse button (#1119) (f92b475)
• cli: add --json output to neru status (#1143) (887101b)
• cli: add --state to the toggles and a macro command (#1144) (3931d0f)
• config: add [macros] for named, reusable action sequences (#1141) (97597b4)
• config: cross-platform role vocabulary for clickable_roles (#1124) (204cacc)
• held_repeat: accelerate step distance while a key is held (#1120) (ef9e12c)
• linux,wayland: resolve focused application (#1105) (ff0c6fe)
• linux,windows: support function keys F13 through F24 (#1118) (7303270)
• linux: event-driven focused-app changes for per-app config (#1115) (8c9500c)
• linux: feed keys through uinput when /dev/uinput is writable (#1130) (04c885b)
• linux: hint arrows for top/bottom placement (#1111) (6a4112b)
• linux: modifier passthrough on Wayland evdev (#1109) (31c84f8)
• linux: mouse action indicator on X11 and Wayland (#1110) (c907c7a)
• linux: multi-monitor parity for X11 and wlroots/KWin (#1125) (a066493)
• linux: smooth cursor animation for X11 and Wayland (#1108) (13dc1ba)
• linux: Wayland hints support, app watcher, and overlay fixes (#1107) (2988aa4)
• modes: add --on-exit flag to modes (#1131) (f8ba0cf)

Bug Fixes

• action: make feed --mode a discrete press-and-release (#1128) (421be62)
• config: accept comma-separated action chains in hotkey bindings (#1132) (593543b)
• config: report an invalid reload instead of blocking on the alert (#1142) (77282a5)
• darwin: enable clang-tidy analysis and fix the findings (#1155) (e18057f)
• darwin: invalidate CGEventTap Mach port before releasing it (#1150) (867e717)
• darwin: keep cursor accurate and visible under Accessibility Zoom (#1117) (b5e5a8b)
• darwin: release AX elements leaked during accessibility priming (#1152) (e1b9e9b)
• darwin: skip WindowServer work for healthy overlays on Space changes (#1151) (da0373d)
• linux: bound AT-SPI calls and surface real hints failures (#1121) (09680e8)
• linux: honor XDG base directory environment variables (#1171) (d22e474)
• linux: render overlays properly on the selected monitor (#1129) (fd2def9)
• linux: stop hints clearing on Wayland refresh (#1113) (83970f0)
• report Linux capabilities from live probes and cover the whole grid (#1136) (fc178e0)
• systray: unify tray icon assets and honor SetIcon everywhere (#1172) (2e63f1e)

Performance Improvements

• linux: resolve focused frame without scanning the whole a11y bus (#1122) (d2934f1)
• linux: use AT-SPI Collection.GetMatches for hint element collection (#1114) (b812044)