hid.click

[Physical HID input — pick this when other automation paths (file APIs, browser automation, OS APIs) cannot accomplish the task, or when the user explicitly requests physical keyboard or mouse input.] Click mouse. Default semantics: (x, y) is an ABSOLUTE screen coordinate — the server queries the OS for the current cursor position (Win32 GetCursorPos / macOS CGEventGetLocation / Linux/X11 XQueryPointer via ctypes) and emits a relative move so the firmware (which is a USB Boot Mouse and only supports relative deltas) lands at the target. Pass relative=true to skip the OS query and send (x, y) directly as a pixel delta. On Wayland and on hosts where the OS cursor query fails, absolute mode returns an error and the caller must use relative=true.

Absolute mode runs a closed-loop converge (query → delta → settle, up to 4 iterations, ≤3 px tolerance) to absorb OS pointer-ballistics non-linearity (macOS scales single HID deltas ~110% in the low-speed segment, so a fire-and-forget move overshoots by 10-90 px). The returned x/y are the actual landing coordinates; target_x/target_y echo the request; converged: true means residual ≤3 px. Click fires regardless of convergence — inspect converged if you need to retry on missed targets.

Optional move_ms switches to glide mode: the move is broken into ~10 ms HID reports over N ms (linear interpolation, then a 3-iter converge to clean up the final landing). Default 0 = snap mode.