SharpHook on Wayland

[TolikPylypchuk]

Update: version 8 with Wayland support has been released. Join the release discussion if you have questions or comments.

TL;DR

SharpHook currently doesn't support Wayland on Linux at all, and I'm planning to implement this support in the nearest future. This discussion describes the fundamental difficulties and solutions for them. Note that the initial Wayland implementation will not support some features - some of them will most probably be implemented later, and some of them will probably not be implemented at all. These changes are going to be in the next major version - v8.

Important: Starting with version 8, SharpHook will require elevated privileges on Wayland by default. I think that changing this default is fine as previously SharpHook didn't work correctly on Wayland at all. There will be a way to revert to the pre-8 mode which works only on X11.

Also note that none of what is described here is final. A big part of this plan was created with the help of Claude Code, and even though it looks plausible, I can't be 100% certain until I actually implement it.

Context - Why This Is Difficult

Wayland is the last major piece of the cross-platform puzzle that's missing from SharpHook. And the main reason is that it's damn hard to do global input listening and input simulation on Wayland. See also the issue in the original libuiohook repo for details.

The main problem is that Wayland is just a protocol, not a display server like X11. Or to be more precise, it's a collection of protocols, and it's also wildly incomplete. Each Wayland compositor can choose which protocols to implement and how. For things that Wayland doesn't cover, each compositor has its own way of doing it.

Another problem is that Wayland is very restrictive - much more restrictive than X11. There is no protocol to listen to input events that are intended for other applications, and while there is a protocol for simulating events, it doesn't cover SharpHook's needs (for example, compositors can decide to ignore events simulated by SharpHook). There is absolutely no way to get the current global mouse position. And many more restrictions. This is great for users in that applications have much less wiggle room to do shady things, but it's very frustrating for application developers.

This is why we need to move to a lower level to handle input events and simulate them, and this requires elevated privileges (but not necessarily root access).

Global Hooks and libinput

I've decided to use libinput as the engine for the global hook. It's installed on pretty much all modern Linux distros except probably some very esoteric ones. Another option was to use evdev, but libinput simplifies a lot of stuff, so I've decided to stick with it instead.

libinput requires access to /dev/input to work and there are several ways to give your application access to it. More on that below.

Unfortunately, there is no way to get absolute mouse coordinates on Wayland without some drastic hacks which are user-noticeable. libinput only posts relative mouse motion events for mice (it can post absolute mouse motion events, but they are posted by touchscreens or by virtual machines usually, not by normal mice). So one major change will be that on Wayland, SharpHook will not raise events of type MouseMoved - instead, it will raise events of type MouseMovedRelativeToCursor. Your application won't have access to absolute mouse coordinates unless you implement getting them yourself.

Since absolute mouse coordinates won't be available, mouse button events and mouse wheel events will not provide coordinates meaning that your application will not know where the mouse has been clicked.

Another missing feature will be that events of KeyTyped will not be available on Wayland, at least for now. I'm planning on making these events disabled by default everywhere since they cause system-wide side effects on Windows and X11, so care should be taken when using them anyway. I think it's possible to derive the character from the current keyboard state and the pressed key using xkbcommon, but the planned Wayland implementation is complex enough as it is, and this feature is not part of core SharpHook functionality, at least in my opition. Note that while XKB started out as an X11 extension, it can be used without X11 and indeed all Wayland compositors use it for keyboard-related stuff.

Event Simulation and uinput

Events can be simulated by writing to /dev/uinput. This also requires elevated privileges. More on that below.

Simulating events via uinput will require registering virtual devices (three of them - a keyboard, an absolute pointing device, and a relative pointing device). The lifecycle of virtual devices can be encapsulated in the EventSimulator class. Currently, an object of this class has basically no purpose other than being a collection of simulation methods, but this will change.

Currently, EventSimulator can be created using new:

var simulator = new EventSimulator();

In the next version, EventSimulator will only be creatable using the static Create method and will implement IDisposable:

var simulator = EventSimulator.Create(); // This sets up virtual devices for uinput
// Use the simulator
simulator.Dispose(); // This destroys the virtual devices for uinput

Setting up virtual devices and waiting for the OS to pick them up is quite slow, so ideally, an EventSimulator should be created early in the application lifespan and reused. Event devices will be reference-counted in libuiohook, so creating a second EventSimulator while the first one is active will be cheap as it will not set up a second group of virtual devices.

Text entry simulation will also be absent in the initial release. The implementation on X11 is already horrible, and on Wayland, it will be even worse, so I have to think it through separately. I think it should be possible to do, but no promises on the timeline.

System Properties

The CreateScreenInfo function (and the global hook itself) will use Wayland protocols directly to enumerate and keep track of screens, their sizes, and coordinates. It will use the xdg-output-unstable-v1 protocol to support fractional scaling if this protocol is available (which it should be on all major Wayland compositors).

GetAutoRepeatRate and GetAutoRepeatDelay will get this info from Wayland directly.

GetMultiClickTime will return 400ms as a hard-coded value since Wayland does not provide this info at all, and this value is the multi-click time on GNOME and KDE.

GetPointerAccelerationMultiplier, GetPointerAccelerationThreshold, and GetPointerSensitivity won't work on Wayland and will always return -1 as Wayland doesn't provide any way to get this info.

Changes to the X11 Mode

On X11, SharpHook will also use libinput and uinput (unless you opt into the legacy mode). This means that SharpHook will also require elevated privileges where it previously didn't. This is a deliberate design decision. Firstly, this will make the Wayland and X11 implementations very similar to each other. You won't have to think about when to set up access to libinput or uinput - you will always have to do it. Secondly, this library is intended for legitimate applications, not anything shady, so I don't support having arbitrary access to input events for any application. This is similar to the model macOS uses - the user must explicitly opt into this functionality and it is up to you as the application developer to convince the user that your application deserves it.

Since libinput posts only relative mouse movement events for mice, the global hook will get the current absolute mouse position using XQueryPointer. This runs the issue of not being synchronous - the global hook will get the mouse pointer position at the time of the hook's execution, not at the time of the event, which may drift. I think this is acceptable since once the motion stops, the last event will report the correct position, and it is usually the one that interests us.

Other functionality should remain unchanged on X11.

Selecting the Mode on Linux

SharpHook will provide multiple libuiohook modes or back-ends for Linux:

• Auto with XRecord (which will be the default one) - selects either the XRecord or Wayland mode, depending on the current session.
• Auto with low-level input - selects either the X11 or Wayland mode, depending on the current session.
• X11 - global hooks will use libinput, event simulation will use uinput, other features will use X11 directly.
• Wayland - global hooks will use libinput, event simulation will use uinput, other features will use Wayland directly.
• XRecord - the pre-8 mode which uses XRecord and XTest for the global hook and input simulation respectively.

SharpHook will provide 4 libuiohook files on Linux instead of just one:

• liuiohook.so
• libuiohook-wayland.so
• libuiohook-x11.so
• libuiohook-xrecord.so

liuiohook.so will be a very thin wrapper and will simply load one of the three back-end files and redirect all function invocations to it depending on the selected mode. Selecting the mode will be possible using the new SetLinuxBackend method. Importantly, once the wrapper has loaded one of the files, it will always redirect to it, so selecting the mode must be done before using any other SharpHook functionality. Each of the four files has an identical ABI.

I previously decided to name the XRecord mode as 'legacy' and retire it in the future, but ultimately decided against it since the new modes are quite restricted compared to it.

Suppressing Events

In short, suppressing events won't be available on Linux in the next version, and will probably not be available in the future at all.

The original libuiohook will use a different strategy for Wayland support and it will support suppressing events, but I believe that the price for this is too high. It will use evdev instead of libinput. Using evdev is lower-level so more work is needed to set up a global hook using it, but it has a feature that libinput doesn't - grabbing devices. When a device is grabbed, only the process that grabbed it receives events from this device. The strategy in the original libuiohook is the following:

• Set up the evdev global hook
• Grab all input devices in the system
• Create a virtual device for each corresponding device
• When an input event is received, it will be received only by libuiohook
• The event handler processes it, and may decide to suppress it
• If the event is not suppressed, it is posted to the virtual device that corresponds to the grabbed device

I believe that this is absurd. The price of a bug may be as large as bricking the user's system and requiring a restart because no input event may be processed at all for whatever reason (and let's hope that your application doesn't automatically run at login). There are no OS-level guardrails - if the hook runs for 1 second, then all user input is delayed by 1 second with no way to unregister a running hook for misbehaving. Thus, I believe that this feature is not worth it, and as far as I know, there are no other ways to suppress events on Linux.

Querying Feature Support

You won't need to check for feature support based on the current platform, SharpHook will provide a way to know whether a specific feature is implemented. In the next version, there will be the following features:

• Suppressing events - enabled for Windows and macOS, disabled for X11 and Wayland
• KeyTyped events - enabled for Windows, macOS, and X11, disabled for Wayland
• Posting text - enabled for Windows, macOS, and X11, disabled for Wayland
• Key auto-repeat events - enabled on Windows, macOS, and the XRecord backend on Linux, disabled on libinput-based Linux backends
• Absolute mouse movement events - enabled for Windows, macOS, and X11, disabled for Wayland
• Absolute mouse coordinates for mouse button and wheel events - enabled for Windows, macOS, and X11, disabled for Wayland
• Pointer properties - enabled for Windows, macOS, and X11, disabled for Wayland

Permissions

As stated previously multiple times, /dev/input and /dev/uinput require special permissions that users don't usually have. There are multiple ways to add them for your application.

The easiest one is to run your application as root. This is not recommended as users will need to unconditionally trust your application and that it won't be compromized.

You can instead create udev rules which grant access to /dev/input and /dev/uinput to non-root users. You can grant these permissions to your own user, but this will mean that any application you run will be able to listen to all events and simulate events. You can also create a separate user specifically for your application, grant access to that user, and then run your application as that user, but that will complicate other stuff for your application.

Or you can use the input group to control access to /dev/input, but udev rules are a more modern alternative, and you will need to use them for /dev/uinput anyway.

SharpHook will also provide a way to cut into the way libinput opens the input files, and how virtual devices are created for highly customized solutions, but it's super advanced, and you probably won't need it. For example, this will allow to create a daemon that runs as root and provides accessible file descriptors to your application, and then SharpHook will use those instead of opening the files directly.

Ultimately, SharpHook cannot recommend one way over the other since this is up to application developers to actually implement the needed plumbing like installer scripts which grant the necessary permissions.

Closing Thoughts

Implementing all this for Wayland is going to be hard. Using it will also be hard, but I don't see other ways to do this. At least I have a plan now, but it's still just a plan, it can still change.

Tell me whether you have any thoughts regarding any part of this plan. Maybe, you will have better ideas - after all, I'm not an expert on the Linux event system at such a low level, almost all of this is new to me.

[Descolada]

Hello,

As you might remember from #169, I ended up giving up on X11 and writing my own evdev hook + uinput synthesis for my project (Keysharp, a cross-platform hotkey and input automation tool). That's been shipping for a little while now, mostly to a few beta testers who broke it in interesting ways, so I've run into a decent number of the things you're planning here.

One general caveat: some of my Linux code is verified on real hardware and some of it is only verified by code review and CI, so I'll try to note which is which where it matters. Additionally, this post is also powered by Claude - without AI I would just have ignored Wayland altogether...

Suppressing events

I do understand that there is real danger in that: I shipped a version where a beta tester registered a single harmless hotkey on Mint/Cinnamon (X11) and lost all keyboard and mouse input completely, only a reboot fixed it. But I consider the danger worth it: namely, how many uses can you think for just monitoring input events without capturing them, besides malicious ones like keylogging? Anything interesting usually requires blocking events, for example implementing hotkeys and key remaps.

The fatal part isn't grabbing devices as such, it's grabbing devices in the same process that runs the user's callbacks. Your objection that a hook taking 1 second delays all input by 1 second with no way to unregister is exactly right for an in-process design, but it mostly goes away if you split it: a privileged broker process owns the grabs and the virtual device and runs no user code at all, and the application is just a client on a socket. The client can be slow, deadlock, crash or get SIGKILLed and the worst case is that suppression stops working.

The things that made this survivable for me, all of which live in the broker and not in the app:

• A per-callback deadline that fails open. Each hook event gets 1 second. On timeout the event is passed rather than dropped, and that hook type gets quarantined with a backoff (1, 2, 4, 8, 16 seconds); five consecutive timeouts kill the client's stream entirely. Keyboard and mouse quarantine separately.
• Leases. A subscription holds a 15 second lease which the client renews by heartbeat every 5 seconds. A client that dies or freezes loses its grabs within 15 seconds.
• The kernel does most of the work. EVIOCGRAB is dropped when the fd closes, so a crashed broker recovers by itself. This is probably the single most important safety property and it's free.
• A physical panic chord handled directly in the broker's event loop, independent of any client — I use Ctrl+Alt+Backspace and Ctrl+Alt+Pause — which releases every grab, drops every subscription and re-emits the chord to the display server.
• Releasing stranded keys. If a grab drops while a key is physically held, the compositor saw the press on the virtual device and will never see the release, so you have to synthesize the releases yourself on the held→released edge. I missed this at first and "recovery" left users with a stuck Ctrl.
• SCHED_FIFO and mlockall on the reader thread, but only while a grab is actually held. An always-on observer shouldn't be preempting the desktop.

That said, if you still don't want it in libuiohook, could you design the extension point you mentioned (the one for how libinput opens the input files and how virtual devices are created) so that a caller can hand you already-grabbed fds plus a replay sink, rather than just open fds? That way libuiohook doesn't have to take any position on suppression, but someone who wants it can build it on top without forking. That seems like a much smaller commitment than implementing it yourself.

A separate Linux input library

A bigger version of that same idea, which may or may not appeal to you: it might be worth considering whether the Linux-specific work belongs inside libuiohook at all, or whether it wants to be its own project.

The starting point is that the privileged parts can't really ship the way the rest of the library ships. Grabbing devices, creating uinput devices and prompting the user for permission all need a root-side install — a systemd unit, udev rules, possibly a resident daemon — and that's a distro packaging problem rather than something you can put in a NuGet package next to a .so. So there's a fairly natural seam there.

But I think that argument extends further than just privilege, and this is the part I'd find most interesting. Most of the things Wayland won't tell you are obtainable from the compositor, if you can get an extension installed into it — a GNOME shell extension exposing a D-Bus method, a KWin script, the Cinnamon equivalent. Those can't ship in a NuGet package either, since they have to be installed into the user's desktop environment and enabled there, so they end up on exactly the same side of the seam as the daemon does.

What follows from that is the useful part, I think. On Wayland the information you need is reachable either from below or from above, and neither one is reachable from an ordinary library. From below (evdev and uinput, with privileges) you get physical events, synthesis, key and button state, and idle time. From above (a compositor extension) you get the absolute cursor position, output geometry including fractional scaling, work areas and so on. Neither half is sufficient on its own, and they complement each other in fairly awkward ways — KWin for instance has idle timeout notifications but no way to query the current idle duration as far as I can tell, so that one has to come from evdev, while the cursor position can only come from the compositor.

So something that owns both halves could be a complete Wayland input automation component rather than just a hook backend: global hooks, event simulation, blocking, absolute cursor position and warping, output enumeration with scaling, work area and idle time, behind one interface, with each piece answered by whichever half happens to be available on that machine. That's roughly the set of things that everyone who hits the Wayland wall currently reimplements separately, so it seems like something that would be worth existing on its own regardless of what libuiohook does with it.

libuiohook's Linux backend would then just consume whatever subset of it is installed, and fall back to its own unprivileged path — legacy X11, or a read-only libinput hook on Wayland — when none of it is there.

I didn't plan this shape, I ended up at it because the constraints pushed me there: a root daemon, plus per-desktop extensions, plus an in-process client that picks what's available at startup. So I suspect it's fairly forced by the problem rather than being a matter of taste.

What I think it would get you:

• Suppression exists for the people who install the privileged component, without libuiohook itself taking any position on it or carrying the risk.
• Elevated privileges stay optional instead of becoming mandatory, which is my main worry about making them the default on X11 (below).
• Feature availability becomes a runtime question about what's installed rather than a compile-time platform constant, which fits the feature-support API you're already planning quite neatly — and it means the Wayland column stops being a list of permanent noes.
• The per-compositor code lives in one place instead of inside libuiohook, which matters because that code is a patchwork by nature and grows a new special case every time a compositor does something differently.
• The Linux side moves fast — Wayland protocols, libei, portals — so it could evolve without libuiohook needing a major version every time.

There are definitely downsides to that, though. It's a third layer (SharpHook → libuiohook → this), and an external dependency - probably not that bad actually, because libuiohook already has external library dependencies. The extension half is also the part that needs the most upkeep, since GNOME in particular breaks its extension API fairly regularly — I maintain a GNOME extension, a Cinnamon one and KWin scripts for this, and keeping those working is easily the most annoying part of the whole thing. And nothing like this exists as a general-purpose thing today, so someone would have to actually build it.

For what it's worth, if any of it turns out to be useful as a starting point rather than something to write from scratch, my projects' keysharp-inputd and the shell extensions are already BSD 2-clause, so if you wish to reuse them then you can do so. I don't have much interest in doing the split myself at the moment, but if it grew into an usable library then I could possibly switch to it myself too.

libinput vs evdev

libinput does genuinely solve device classification for you, which is annoying in raw evdev — a gaming mouse advertises a full keyboard, a laptop has three or four nodes that all look like keyboards, power buttons show up as EV_KEY devices, and so on. But there are a few behaviours it changes that I think are worth knowing about first:

• libinput filters out key autorepeat. The kernel input core generates repeat events (EV_KEY value 2) for devices with EV_REP, and as far as I can tell libinput drops them and reports only press/release. XRecord in your legacy mode does surface repeats and so does the Windows low-level hook, so holding a key would give N KeyPressed events on Windows and legacy X11 and exactly one on Wayland (which could be confusing to the user: they get repeated events visually but not from libinput). This is sort of the mirror image of my old issue X11 key autorepeat detection #169, and it's an API difference your feature-support list doesn't currently cover.
• libinput configuration is per-context, not global. Your context gets the defaults, not the user's compositor settings, and there's no protocol to read theirs. So tap-to-click, natural scrolling, the accel profile, left-handed button mapping and disable-while-typing will all differ between what the compositor does and what SharpHook sees — a touchpad tap becomes a click for every other application and not for you, and a left-handed user's primary button is BTN_RIGHT to the compositor and BTN_LEFT to you. With raw evdev this ambiguity doesn't come up, because you're reporting physical truth and the divergence is explicit.
• Accelerated vs unaccelerated deltas. If you do go with libinput, I'd use libinput_event_pointer_get_dx_unaccelerated() for MouseMovedRelativeToCursor, because the accelerated value is your context's acceleration curve, which isn't the one the compositor actually applied to the cursor.
• The left/right swap is two-sided. This is an open bug in my own project so I might as well mention it: if your hook reports physical buttons and your simulator also emits physical buttons, both halves are consistently "wrong" and a left-handed user's setup still works. Fix only the simulator and you get a double swap, which is worse. Probably best to decide once whether MouseButton.Button1 is physical or logical and then do both boundaries at the same time.

None of these are blockers, I'd just document them rather than let people discover them.

The X11 backend

I'd think twice about moving X11 onto libinput and uinput as well, and not really because of the privileges — the bigger issue I think is that it changes what the hook is able to see at all.

XRecord records at the X protocol level, so as far as I know it sees everything the server dispatches, including events injected with XTest. An evdev or libinput hook only ever sees physical hardware, so every X11-level synthetic event becomes invisible to it: xdotool and similar tools, on-screen keyboards, accessibility software, and VNC/RDP servers, which generally inject through XTest. Someone running an application inside a remote session could end up seeing no events at all, which would be a fairly confusing bug report to receive. This is a downside in my own project as well.

There's a smaller fidelity point too. XTest injection goes through the X server, so it respects the server's pointer button mapping and lands as ordinary core events, and XWarpPointer is pixel-accurate. uinput injection goes in underneath all of that, so it's subject to pointer acceleration and to the physical-vs-logical button mapping I mentioned before, and absolute positioning has to go through a normalised coordinate range which is lossy. So on X11 the current injection path seems better than the one that would replace it.

What the change does genuinely buy on X11 is injected-event detection, since if you inject through your own uinput device you can tag it, whereas XTest events are indistinguishable from physical ones. That's a real gap and it's one of the reasons I gave up on X11 myself, so I do understand the appeal — but it's a fairly specialised need, and I don't think it's worth making every existing consumer require root just to keep working.

So what I'd suggest is keeping XRecord + XTest as the default on X11 and offering the libinput/uinput path as opt-in for applications that specifically want injected-event detection, or want identical behaviour on both session types. I'd also have Auto select on capability rather than on session type, so that if /dev/input isn't accessible it falls back instead of failing — you're building the feature-query API that makes that honest anyway.

Detecting your own injected events

I didn't see this mentioned in the plan and I think it's fairly important. Once the uinput simulator and the libinput hook are running in the same process, your own simulated events come straight back into your own hook, and as far as I can tell there'd be no way for the application to tell them apart from real input. Anything that simulates input in response to input runs into this — a macro where one key triggers a sequence of keystrokes, a turbo/auto-repeat feature, or even just an application counting keystrokes and silently counting its own. In the case where the response includes the trigger key itself it's an infinite loop. On Windows LLKHF_INJECTED lets you break out of it, so this would be a Linux-only footgun.

So the virtual devices need to be tagged and that needs to be exposed on the event. I identify my own device by name and vendor/product together rather than name alone (see the keyd note below for why), and libinput should give you what you need via libinput_event_get_device → libinput_device_get_udev_device.

One distinction that turned out to be useful in my case: I suppress the pass-through replay events from re-entering the hook, since those are just the user's own physical events being let through and re-reporting them would be a duplicate, but I deliberately don't suppress events from an explicit simulation request — I only flag them. That way the application can decide for itself whether its own synthetic input should trigger its own handlers, which is sometimes wanted and sometimes not.

uinput gotchas

Device visibility. This one is silent and took me a long time to track down. My beta lockout above actually had two causes, and the second was that events replayed on my uinput node were unreadable by the session's display server for users who aren't in the input group — hotkeys still fired, but everything else died. It's invisible in development because developers are either root or in input. The fix was a udev rule putting TAG+="uaccess" on my virtual devices by name, numbered 70- so it sorts before systemd's 73-seat-late.rules. I've verified this one on hardware: with the rule installed getfacl on the device node lists the session user and ordinary input passes through fine on a user not in input, and removing the rule reproduces the lockout on demand.

I think this applies to your simulation path too even though you're not grabbing, because a uinput device created by a root helper is root:input 0600, and if the user followed your advice and did not join the input group then the compositor may not be able to open it and simulated events would silently do nothing. Might be worth testing simulation on a session where id -nG | grep -w input prints nothing, since that's the configuration your own security guidance produces.

Device creation latency. UI_DEV_CREATE returns before anything has actually picked the device up, and events written in that window are silently lost. My privileged test harness uses a two second settle delay for this. Since you're making EventSimulator.Create() explicit and reference-counted anyway (which I think is the right call), it might be worth watching udev for the add event on your own device and blocking until it shows up, or at least documenting that the first events after creation can vanish.

Several applications at once. Reference-counting the devices within one instance makes sense, but the refcount is presumably per-process, so ten applications using SharpHook would mean ten sets of three virtual devices, each one costing a udev event and a device-added round trip in every compositor and libinput context on the machine. What I'd worry about more than the clutter is identity: if every instance registers its devices with the same name, vendor and product, then a hook in one application can't tell its own injected events from another SharpHook application's, which makes the tagging I mentioned above a lot less useful than it looks. Putting something per-instance into the device identity, like the pid in the device name or a per-instance product id, would fix that fairly cheaply. It might also be worth checking what happens when two plugins in the same process each load their own copy of the native library — I'd assume dlopen returns the same handle and the refcount is shared, but that seems like something to confirm rather than assume.

Other grab-and-replay tools. This was the first and actual cause of the lockout: keyd grabs real keyboards and re-emits through its own virtual keyboard, so I ended up grabbing keyd's virtual device while my grabs of the real devices failed with EBUSY, which gave two layered grabbers and a dead session. I fixed it by masquerading my synth devices under keyd's vendor ID so that keyd's is_virtual filter never re-grabs my output, plus a soft After=keyd.service ordering hint. input-remapper, keyd, Interception Tools, evsieve and xremap are all out there doing this, and any two of them will fight. You'd be affected by this even without grabbing anything yourself, though not by double-counting — a grab is exclusive, so while keyd holds the real keyboard neither libinput nor a raw evdev reader gets anything from it, and what you see instead is keyd's virtual device. The events reaching the hook are therefore post-remap, and the device they're attributed to is a virtual one rather than the actual hardware, so anything that assumes a device id corresponds to a physical device, or that a keycode is the key the user physically pressed, would be wrong on such a system. Double-counting would only come up with a remapper that injects without grabbing the original, which the well-behaved ones don't do.

Batch atomicity. Windows SendInput is atomic and uinput isn't, so physical input can interleave between two members of a simulated sequence and without a grab there's nothing you can do about it. Probably just worth a line in the docs.

Absolute mouse position

I think this might be a bit too pessimistic. There's no portable way, but there is a way on most of the desktops people actually run, and I ship all of these:

Desktop	How
KDE / KWin	D-Bus into KWin scripting: workspace.cursorPos
GNOME	a shell extension exposing a D-Bus method returning global.get_pointer()
Cinnamon	same approach as GNOME
Hyprland	its IPC socket ($XDG_RUNTIME_DIR/hypr/<sig>/, older builds used /tmp/hypr/<sig>/)
sway	not available as far as I can tell — its IPC genuinely doesn't expose it, I gave up
absolute devices	last ABS_X/ABS_Y from evdev, scaled across the virtual desktop

The GNOME and Cinnamon ones need a shell extension, which is a reasonable thing for an application to ship and an unreasonable thing to ask of a library. So I'm not suggesting you implement all of these — more that you could expose a pluggable position provider interface so applications can supply one, with the evdev/absolute-device path as the default and a clean "unsupported" otherwise. That turns it from impossible into merely inconvenient for your users at almost no cost to you, and it's more useful than a hard false in the feature table. The same would then apply to the coordinates on mouse button and wheel events — if a provider exists you can attach one.

KeyTyped and xkbcommon

I do this on both X11 and Wayland with xkbcommon and it's honestly not that bad, maybe a day of work for the main path (build the keymap, resolve the keysym at the current group/level, convert to UTF-8) plus a longer tail. The tail is mostly dead keys — you need a table mapping dead keysyms to a (combining mark, spacing form) pair, then NFC-compose with the following base character and fall back to the spacing form when the sequence doesn't compose, so dead_grave then z gives `z — and layout changes, which on Wayland arrive via wl_keyboard.keymap/modifiers so it has to be a listener rather than a one-time read.

I do think it's worth doing eventually since it's what makes text expansion possible on top of the library, but I agree it isn't something to block v8 on, and I strongly agree with making it opt-in everywhere.

Permissions

Two things I'd add to that section.

The first is active session gating. With raw /dev/input access the listener also sees the lock screen password, and on a multi-seat or fast-user-switching machine it sees the other user's typing, and a udev rule granting a user or the input group is a permanent grant that doesn't care about sessions. I gate on logind's active seat0 uid, so a switched-away user's connections stay open but go inert (no hooks, no grabs, no state queries, no synthesis), with a generation fence that discards in-flight work from the old session before the new uid is published, and it fails closed if logind can't identify an owner. Even if SharpHook doesn't do anything about it, I think it deserves a paragraph in the docs.

The second is that the broker approach also answers the objection you raise about udev rules yourself — that granting your own user access means every process you run can keylog. A broker can authenticate its clients with SO_PEERCRED plus a hash of /proc/<pid>/exe and the argv, prompt per application, and persist both allow and deny decisions. (A persisted deny mustn't re-prompt, and the way back has to be explicit and rate-limited, otherwise a hostile process just spams dialogs until the user clicks yes.) That gets fairly close to the macOS consent model you mention wanting, without a blanket grant. Mine is in native/keysharp-inputd/ in the Keysharp repo if it's useful to look at, the protocol doc there describes the whole thing.

Smaller things

• The four .so files. The cost is four ABI-identical artifacts plus a latch with ordering rules that users will get wrong. I assume the reason for splitting is to avoid linking libX11 on a Wayland-only machine, but dlopening the system libraries lazily gets you the same thing in one file — that's what I do, one binary with every X11/Wayland/D-Bus entry point resolved and probed at runtime. If you do keep the split, I'd at least make the mode explicit with something like Initialize(backend) that throws if called twice, rather than a silent first-use latch.
• Multi-click time. 400ms hardcoded seems fine, but gsettings get org.gnome.desktop.peripherals.mouse double-click and KDE's DoubleClickInterval in kdeglobals are cheap reads if you want to be exact on the two desktops that cover most users.
• xdg-output-unstable-v1 seems right to me — wl_output v4 added name and description but logical position and size still come from xdg-output. Two caveats: a root daemon has no Wayland connection, so if any of this ever moves into a privileged helper it loses screen enumeration; and with fractional scaling on mixed-DPI monitors, logical and physical pixels diverge and there's no single global pixel space. It's worth deciding and documenting which one SharpHook's coordinates are, because otherwise callers will mix them — I ran into this and the rule I settled on is to never add a physical origin to a logical size.
• libei might be worth a look for simulation. Via an xdg-desktop-portal RemoteDesktop session you get compositor-blessed injection with a consent dialog and no elevated privileges at all, and recent Mutter and KWin support it. It would address the "compositors can decide to ignore events simulated by SharpHook" concern directly, since portal-sourced input is the sanctioned path. I haven't actually used it myself so take this with a grain of salt, and it clearly can't cover everything (no global listening, and smaller compositors won't have it) so uinput would still be the fallback — but as the default simulation route it might let a lot of your users skip the privilege setup entirely. Might be worth a spike before committing to uinput-only.

Conclusion

I think the crux of the issue is that Linux, compared to Windows and macOS, is fragmented and doesn't have a centralized API to implement most of libuiohook functionality. Possibly not the response you want, but I think the solution is a separate project to do that, and then let libuiohook (and Keysharp?) consume that. Possibly even two separate projects, because I couldn't find a good pre-existing library to manage permissions with enough granularity and a good UI.

Let me know which direction you want to take, I'm happy to go into more detail on any of this ;)

[TolikPylypchuk]

Hey! Thanks for the great write-up!

Just when I thought that I had Wayland mostly figured out, I get a bunch of new issues thrown at me 😅

I will answer your points one by one, but first, the most important thing - I understand why you made the decision to have a separate daemon process, DE extensions, etc., but I don't think I can realistically do that since SharpHook is just a library - it cannot ask its users to install a privileged process or an extension. So I have to work with what I have.

And another thing, the main reason why I don't want to use any compositor-specific stuff is quite simple - I just don't want to maintain any of it. It drastically complicates maintenance and that's a price I don't want to pay.

To be honest, SharpHook was created in the first place as an extracted piece of functionality from my other project - Keyboard Switch. And that project doesn't even use a mouse hook, so I've already done much more than I personally needed here.

Now, for your points one by one:

Suppressing events - as I've said previously, as a library SharpHook cannot affort to have a multi-process setup. Maybe, I'll add extension points in the future to support this, but for now, I will leave it as-is. But I think that a library for listening to input events without the ability to suppress them still has merit. For example, if you want to install a hot-key and react to it in a certain way, you most probably don't need to suppress that event for the rest of the system.

A separate Linux input library - I thought about pulling some Linux-specific stuff into a separate library that users can load separately, but decided against it since it's a lot of work.

libinput vs evdev - thanks for pointing out these behaviours with libinput, I didn't know about them, and will have to investigate them.

Regarding X11 - you raise a a good argument about XTest events becoming invisible. Maybe, I will revisit the decision to call the XRecord-based back-end the 'legacy' one and continue supporting it. I may also add other ways to select the back-end (XRecord on X11 and libinput/uinput on Wayland, or as you've said, select based on capability) - I'll also think about it.

Detecting your own injected events - events are reported as injected if they originate from a device whose syspath is in /sys/devices/virtual/, so the users of SharpHook will be able to ignore emulated events.

uinput:

• Claude already told me about the udev rule specifics, so I will document them.
• The code which initializes the virtual devices already waits for them to be registered.
• I'll add a string parameter to EventSimulator.Create() so that virtual devices can be named after the application that uses them.
• Batching is possible only on Windows, and that's fine - on macOS, events are also not batched.

Absolute mouse position - nothing will stop the users of SharpHook from getting the absolute mouse position using one the means you described, and then adjusting it using relative motion events (or reading the absolute position anew). Sure, it's inconvenient, but it's just outside of the scope of SharpHook.

KeyTyped - yeah, I also think that it's doable, but still, I will implement it later.

Permissions - as far as I understand, if we enable access to /dev/input via udev rules, then it will be accessible only during an active session, so SharpHook will not see the user entering their password. But I will need to test it. This is also out of scope of SharpHook since it's up to application developers to decide how to enable permissions for /dev/input and /dev/uinput.

"The cost is four ABI-identical artifacts plus a latch with ordering rules that users will get wrong." - I don't understand this point. The very fact that there are 4 files will be an implementation detail, and users of SharpHook wouldn't need to care about it at all, the correct file will be loaded and used. If they need to override the back-end before using any other SharpHook API - sure they might get it wrong at first, but it will be documented, so they will figure it out. I think that having four different files is better than calling many, many functions dynamically.

Multi-click time - I will probably add a way to redefine it so that users of SharpHook can read the compositor-specific properties themselves and set it, but that can wait for a future version.

I think it's possible to pass the Wayland connection to a process that runs under root, so if an application developer decides to run a SharpHook-powered application as root, they will need to do additional setup, but it's doable.

libei has the same problem you've described with XTest - an input hook won't see injected events. Which is not strictly a problem, but still a bit inconsistent. Also, since we require /dev/input now, I think also requiring /dev/uinput has a nice symmetry to it.

And another thing - I don't have infinite free time and desire to work on this project. So, for me, the most important thing is to make this library work on Wayland at least partially - this is better than nothing at all. For me personally (as a user of SharpHook), having keyboard events work on Wayland would unlock Keyboard Switch on it, so that's all I need right now basically. Having mouse also partially work is a nice bonus.

[TolikPylypchuk]

I've decided to keep the current X11 backend and renamed it from 'legacy' to 'XRecord' since the new Linux backends really are quite restrictive. Also, I've added more ways to configure the Linux backend, and the XRecord backend is the default one on X11.

Regarding libinput having contextual configuration - this is just something that we will have to live with for now. I don't know how to fix it without getting some settings from compositors, and that is curently out of the question since it's a lot of work. So, SharpHook will use the default libinput config except that it turns tap-to-click on, which translates tap events to mouse click events (it's off by default in libinput).

And regarding libinput_event_pointer_get_dx/dy_unaccelerated - these functions return raw device coordinates which may not be what we want. So I will continue using libinput_event_pointer_get_dx/dy even if the acceleration will be wrong if the user changed it in settings.

All in all, it looks like the libinput backend for global hooks will be shaky at best, but as I've said, it's better than nothing.