Add native KWin support (libei pointer + ScreenShot2 target detection)

[mcdax]

Implements #44 — native KWin support, gated behind a new optional kde Meson feature so the wlroots path and minimal builds are unchanged.

Pointer movement & clicks

KWin doesn't implement wlr-virtual-pointer, so the pointer is driven through libei over an EIS socket obtained from KWin's org.kde.KWin.EIS.RemoteDesktop.connectToEIS D-Bus method — the approach described by @Gliese852 in #44 (thanks!). move_pointer() is now a small dispatcher that picks the wlroots backend when wl_virtual_pointer is present, otherwise the KDE backend.

A couple of things that were needed to make it reliable on KWin:

• the D-Bus connection that called connectToEIS must stay alive for the lifetime of the EIS session (KWin tears the session down otherwise);
• ei_dispatch() has to run before poll() so the initial libei handshake is driven, and an ei_ping() round-trip flushes the final click before teardown.

Target auto-detection (floating + detect)

Since KWin also lacks wlr-screencopy, the screen is captured via KWin's org.kde.KWin.ScreenShot2 D-Bus interface (CaptureArea) and fed into the existing OpenCV pipeline unchanged. This path is built only when both opencv and kde are enabled. Because ScreenShot2 is a restricted interface, the installed desktop file now carries X-KDE-DBUS-Restricted-Interfaces=org.kde.KWin.ScreenShot2 and uses an absolute Exec (generated via configure_file); capture only works for an installed binary, not from the build tree.

Build

meson setup build -Dkde=enabled            # pointer support
meson setup build -Dkde=enabled -Dopencv=enabled   # + auto-detection

New dependencies (only with -Dkde): libei and an sd-bus implementation (libsystemd, or basu on non-systemd systems). wl-kbptr --version prints (kde).

Testing

Tested on KWin Plasma 6 (Wayland):

• pointer jumps to exact global coordinates including on a second monitor; left/middle/right clicks work;
• auto-detection captures via ScreenShot2 and the OpenCV pipeline returns sensible targets;
• a build without -Dkde and a wlroots compositor behave exactly as before;
• added a unit test for the global→region coordinate mapper.

Known limitations

• ScreenShot2 auto-detection requires the program to be installed (allow-list entry), so it can't be exercised from the build tree.

Happy to adjust naming, the feature split, or anything else to fit the project's conventions.

[moverest]

Thank your for your PR, this is an interesting addition. I don't use KDE thus why I didn't actively worked on supporting it, however it's still something I'm interested in supporting.

I like the fact that this is all optional since it inevitably brings new dependencies. In fact, that's the reason why the detection feature is optional.

I've tested it on my machine and I have a few observations:

• When the program doesn't have access to query the org.kde.KWin.ScreenShot2 API it will run into a segmentation fault when trying to do the detection.
• It doesn't reliably click on my machine. I'm not sure if it's because the overlay surface doesn't disappear fast enough thus gets the click event or if it's something else. I tried adding a one second delay but it didn't seem to reliably work either (but maybe it help?). I need to investigate further. Is it doing this on your machine? I've ran it with Arch's plasma-desktop 6.6.5-1.
• Setup:
  • Since I don't use KDE, I'm not sure what would be the best way to configure the software. From my understanding, it has to run through the wl-kbptr.desktop to get the necessary permissions. I've been able to set a short cut in the config panel, but I'm not sure how we can pass arguments to it (e.g. to change the modes or just use a different configuration file). The way I've ran it is by creating a secondary file with the options I needed. That can't be the only way, is it?
  • I'm also asking so that this could be put into the README with a sub-section in the Setting the bindings section with instructions on how to configure it for KDE. Though, this doesn't have to be done in this PR.
  • The following is a bit of a nitpick: The terminology is a bit fuzzy, we're talking about KWin but the option is kde. I think it would make sense to just say everywhere kwin, i.e. the compositor (and only mention KDE in the README) as it's really what we're targeting.

I haven't looked into the code in detail yet. I also haven't tested a multiple monitor setup either. I will do that a bit later.

[mcdax]

Thank you very much for your input! I'll analyse the issues over the next few days.

Interestingly, I don't experience any delay or click issues at all (KDE Plasma 6.6.4 on Kubuntu 26.04). I'm going to test on a few more machines.

▎ The way I've ran it is by creating a secondary file with the options I needed. That can't be the only way, is it?

That's exactly how I tested it too, since I can't think of another way that wouldn't make things even more complex. I'll give it more thought. There's also the issue that you can start the binary multiple times, which leads to strange effects.

Multi-monitor is still a limitation: it currently only works on the active output.

[mcdax]

Hi @moverest,

I can't reproduce it on my other machine either, unfortunately. (Arch with recent plasma-desktop)

I did a small refactor around the roundtrips and the EIS connection handling. It now opens one connection and reuses it instead of reconnecting on every keystroke and I also added some extra debug logging.

Could you pull the latest commit, build with -Dkwin=enabled, run it again, and check if the problem still happens? If you paste the logs (run it from a terminal, the info: lines), that'd really help to see where it breaks on your machine.

Btw, I don't think the overlay is stealing the click: its input region is empty, so clicks pass straight through to the window underneath. That probably also explains why the 1s delay didn't help.

Thanks!

PS: Most of the code is AI generated, I still have to revise esp. the comments.

[mcdax]

btw. Most of the code can also be used for GNOME support. (In the long run)

[bybv]

Tested this branch at cbbb0a9 on Arch Linux with Plasma 6.7 (kwin_wayland, libei 1.6.0), built with -Dkwin=enabled -Dopencv=enabled, single monitor.

Results:

• Pointer motion and clicks work reliably. The instrumentation logs show the motion/press/release frames each round-tripping (press_to_release ~27–35 µs between send timestamps), and every click registered in real use across tile,click, tile,bisect (g/h/b clicks), and floating,click with source=detect. We could not reproduce the unreliable/delayed click with this revision.
• Target auto-detection via ScreenShot2 also works with the installed desktop file carrying the X-KDE-DBUS-Restricted-Interfaces entry.

Two small build issues on current Arch, where OpenCV is now version 5 (pkg-config name opencv5):

1. meson.build looks up dependency('opencv4') — needs dependency('opencv5', 'opencv4') (meson tries them in order).

2. OpenCV 5 moved cv::boundingRect into the new geometry module, so src/target_detection.cpp fails to compile without:

   #if CV_VERSION_MAJOR >= 5
   #include <opencv2/geometry.hpp>
   #endif

With those two changes it builds and runs cleanly. Happy to provide logs or test further revisions.

---

Transparency note: this comment was written by Claude Code (an AI assistant), which set up and tested the build together with this account's owner on their machine; the owner reviewed and approved it before posting.

[bybv]

Follow-up on the unreliable-click issue @moverest reported: we can now
reproduce it, and it turns out to be toolkit-dependent, not a race with the
overlay.

Symptom: with the branch at cbbb0a9 (Arch, Plasma 6.7.3, libei 1.6.0),
the injected click registers in Qt apps (Dolphin) but is silently dropped in
Chromium-based apps (tested Brave running as a native Wayland client — no
XWayland involved). The cursor moves, the instrumentation logs show the
press/release frames acknowledged by KWin, but the app never reacts.

Cause (as far as we can tell): the per-frame round-trips order the events
correctly, but press and release still go out only ~30–40 µs apart, so the
client sees a button press and release carrying the same millisecond
timestamp — a zero-duration click. Qt accepts that; Chromium's input pipeline
discards it. This would also explain why a delay before the click sequence
(the 1 s you tried) didn't help: the gap that matters is between press and
release.

Fix that works for us: sleeping ~60 ms before the press and again before
the release makes clicks register reliably in Brave as well as Qt apps.
Locally we made it tunable via an env var:

@@ pointer_kwin_move()
+    const char *delay_env = getenv("WL_KBPTR_KWIN_CLICK_DELAY_MS");
+    long click_delay_us = (delay_env ? atol(delay_env) : 60) * 1000;
+
     uint64_t t_motion = ei_now(s->ei);
     ei_device_pointer_motion_absolute(device, tx, ty);
     ei_device_frame(device, t_motion);
     flush_until_pong(s);
@@
+        if (click_delay_us > 0) {
+            usleep(click_delay_us);
+        }
         t_press = ei_now(s->ei);
         ei_device_button_button(device, btn, true);
         ei_device_frame(device, t_press);
         flush_until_pong(s);

+        if (click_delay_us > 0) {
+            usleep(click_delay_us);
+        }
         t_release = ei_now(s->ei);

For upstream it probably makes more sense as a proper config option (or just a
sane hardcoded gap) than an env var — happy to test whatever form you prefer.
A press→release gap on the order of tens of ms is what real hardware produces,
so it seems safe to always apply.

[mcdax]

Thanks a lot for the analysis and recommendations! Sadly, I hadn't much time to look into it yet. I'll try go though all your points in detail this week.

[bybv]

I am actively using this now and doing a few tweaks that could be system specific. Anything that isn't I will try to contribute. Thank you so much for everything!

On Wed, Jul 29, 2026, at 13:58, mcdax wrote: *mcdax* left a comment (moverest/wl-kbptr#97) <#97 (comment)> Thanks a lot for the analysis and recommendations! Sadly, I hadn't much time to look into it yet. I'll try go though all your points in detail this week. — Reply to this email directly, view it on GitHub <#97?email_source=notifications&email_token=BCEBN5QUIGYRWGS253GXGN35HIUM5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJSGA4TONRQGQ32M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5120976047>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BCEBN5R2XIS6NYC5HXNSRCL5HIUM5AVCNFSNUABFKJSXA33TNF2G64TZHM3DGMBRHE3DSOBYHNEXG43VMU5TINRVHEYDQMZWGU22C5QC>. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BCEBN5WJ7ANGTPJLEK33GNL5HIUM5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJSGA4TONRQGQ32M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/BCEBN5UGW7GDC6EWU5PJNKT5HIUM5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMJSGA4TONRQGQ32M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you commented.Message ID: ***@***.***>

_S