Skip to content

docs(research): Event-driven pointer input versus the 16 ms poll - #241

Merged
omesser merged 1 commit into
mainfrom
docs/research-event-driven-input
Sep 2, 2026
Merged

omesser merged 1 commit into
mainfrom
docs/research-event-driven-input

Conversation

@omesser

@omesser omesser commented Sep 2, 2026

Copy link
Copy Markdown
Owner

Why

#236 fixes #182 by patching the 16 ms poll with an edge bit. The owner asked whether the poll should go entirely in favour of reacting to input events — the design #183's comment proposes. That comment rests on a permission claim nobody had checked. This is the check.

What changed

One research note, docs/research/event-driven-input-vs-polling.md, and the docs/research/ directory it lives in (the repo had none; ADRs record decisions taken, this is research feeding one). Every platform claim is cited to Apple, X.Org, Wayland, tao, or x11rb sources; three claims Apple's docs do not settle are marked unverified rather than asserted.

The short answer, from the note:

  • macOS: unverified, not confirmed. Apple documents the CGEventTapCreate gate for key events and says nothing about mouse-only listen-only session taps. The relevant TCC class is Input Monitoring, not Accessibility as The frame loop keeps polling at 60Hz when the desktop is idle #183 says. Nothing can be designed on that premise until a spike tests it against a fresh TCC database.
  • X11: event-driven and prompt-free via XI2 raw events on the root window. x11rb has the xinput feature; the repo does not enable it yet.
  • Wayland: no global pointer at all. "Degrade to a slow poll" is wrong — there is nothing global to poll. It is webview-only.
  • Events do not remove the hit-test. The cursor-arrives-over-the-art transition costs the same test per motion event as per tick. The loop can block on recv() when idle only if a mouse-moved tap is also permission-free. The saving is bounded to the fully idle case.
  • fix(shell): See a click that begins and ends between two polls #236 is correct today and survives The frame loop keeps polling at 60Hz when the desktop is idle #183. A channel drained once per tick and an edge bit are the same thing for a sub-tick down+up; Witness::take is the one-bit queue. A tap would change the producer, not the read.

Recommendation: merge #236; re-scope #183 into a permission spike before any loop rewrite.

How to verify

Read the note against its citations. The macOS spike it proposes is the next concrete step: tccutil reset ListenEvent, create a mouse-only kCGEventTapOptionListenOnly session tap, observe whether a prompt appears or the tap returns null.

Related: #182, #183, #236.

Research for #183, prompted by #236. X11 raw events are permission-free;
Wayland has no global pointer; on macOS the Input Monitoring gate for a
mouse-only listen tap is unverified and needs a spike before any rewrite.
#236's edge bit is the one-bit form of the event queue and stays correct.
@omesser
omesser merged commit b9686d0 into main Sep 2, 2026
2 checks passed
@omesser
omesser deleted the docs/research-event-driven-input branch September 2, 2026 13:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A click shorter than one frame can miss the overlay button latch

1 participant