Skip to content

v1.4.0 — Wayland-native Linux support

Latest

Choose a tag to compare

@miisodev miisodev released this 21 Nov 16:22
803c0d9

Handy's first published release, and the one that makes it actually work on the desktop it gets installed on most: a GNOME Wayland machine.

Why

The 1.3.0 code was built and green on CI, but installing it on a real Wayland desktop found four things no headless run could find:

  • backend auto-selection picked the X11 backend whenever DISPLAY was set — XWayland always sets it — so every GNOME Wayland install landed on a backend that cannot see native windows;
  • screen capture was broken outright: the Shell's screenshot API rejects third-party callers (since GNOME 41) and the fallback list had no route GNOME serves;
  • key steps didn't work with ydotool, the only input tool that works on GNOME Wayland;
  • the doctor reported all-OK while capture failed at runtime.

What's new

  • Wayland-native by default — auto-selection prefers the CLI backend on Wayland sessions, even with DISPLAY set; explicit HANDY_BACKEND still wins.
  • freedesktop portal capture — the portal is the first route on Wayland (gdbus, zero new dependencies), the fresh capture is picked up from the Pictures directory with signature and size checks, consumed after the read, and every route retries in order with its error named.
  • ydotool keyboard support — a Linux EV_KEY map in keys.ts (same shape as the Darwin and Win32 maps) drives key/keyTap/keyDown/keyUp; chords send modifiers down, the key down and up, and modifiers back off in reverse. ydotool is only selected when a daemon socket is actually reachable, so a dead daemon can't take key taps away from a working wtype.
  • Real pointer position on the ydotool path — getMousePosition() reads the actual cursor through XWayland (cached probe), so the (0, 0) corner-slam failsafe keeps seeing a human-driven pointer.
  • Truthful doctor — session type, capture routes and last successful route on the Wayland side; a Wayland-session warning on the X11 side.

Plus the review-driven hardening from CodeRabbit and Codex: portal captures serialized and scoped to the portal's own naming, routes accepted only after their bytes decode, the portal probed before it is advertised, shift-ownership tracking so a held modifier is never cut short, and own-property key lookups.

Verified end-to-end on Ubuntu 26.04 GNOME Wayland (1600x900): portal capture ~350-850 ms per shot, key meta → type calc → key return launching Calculator, and an in-process MCP see → click-by-mark landing pixel-exact on the marked element.

Install: npx -y @miisodev/handy install · npm: npm i -g @miisodev/handy · full docs in the README.