tapir-autoclicker 0.2.0__tar.gz

tapir_autoclicker-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Sylla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tapir_autoclicker-0.2.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: tapir-autoclicker
+Version: 0.2.0
+Summary: Small Wayland-friendly autoclicker with a Qt UI
+Author: Pierre Sylla
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PierreSylla/tapir-autoclicker
+Project-URL: Issues, https://github.com/PierreSylla/tapir-autoclicker/issues
+Keywords: autoclicker,wayland,hyprland,uinput
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PySide6>=6.5
+Requires-Dist: evdev>=1.6
+Requires-Dist: tomli-w>=1.0
+Dynamic: license-file
+
+# Tapir
+
+A small autoclicker for Linux Wayland desktops, with a compact Qt window.
+
+Clicks go through a virtual `uinput` mouse, so they work under any compositor. No X11 tools (xdotool, pynput, PyAutoGUI) are involved.
+
+## Features
+
+- Interval in hours, minutes, seconds and milliseconds (10 ms minimum), with an optional random variation of ± N ms
+- Left, right or middle button; single or double click
+- Repeat N times or until stopped, with a click counter
+- Optional countdown (0–10 s) when starting from the window or the tray, to give you time to place the cursor
+- Clicks at the current cursor position and never moves the cursor
+- Global start/stop hotkey: a bind managed in Hyprland, or an evdev fallback elsewhere
+- Command line and Unix socket: `tapir toggle | start | stop`
+- Tray icon coloured by state (grey stopped, amber countdown, green running)
+- English or French interface, following the system language until you pick one
+- Settings saved on every change
+
+## Installation
+
+### Arch Linux / CachyOS package
+
+```
+cd packaging
+makepkg -sif
+```
+
+The PKGBUILD builds the **last commit** of this repository: uncommitted changes, including new files that are not committed yet, are not included. `-f` rebuilds the package even when one with the same version was built before; without it, makepkg reinstalls the old file. It installs the `tapir` command, the desktop entry and the udev rule, and pacman reloads udev for you.
+
+### With pipx or pip
+
+```
+pipx install tapir-autoclicker
+```
+
+evdev ships no prebuilt wheel, so pip compiles it: you need a C compiler, the Python headers and the kernel headers (Arch: `base-devel`; Debian and Ubuntu: `build-essential python3-dev`). The udev rule and the desktop entry are not installed this way: see Permissions.
+
+### From source
+
+```
+sudo pacman -S pyside6 python-evdev python-tomli-w
+python -m tapir
+```
+
+Python 3.12 or newer. On other distributions, install PySide6, evdev and tomli-w from your package manager or with pip. From a source checkout, replace `tapir` with `python -m tapir` in the commands below.
+
+## Permissions
+
+Tapir creates its virtual mouse through `/dev/uinput` and needs write access to it. Many systems already give it to the logged-in user (Steam's `60-steam-input.rules` does, for example). To check:
+
+```
+test -w /dev/uinput && echo ok
+```
+
+If it is not writable, install the udev rule shipped with Tapir. The Arch package does it for you; from source, run:
+
+```
+scripts/setup-permissions.sh
+```
+
+The script asks for confirmation, then runs:
+
+```
+sudo install -Dm644 packaging/70-tapir-uinput.rules /etc/udev/rules.d/70-tapir-uinput.rules
+sudo udevadm control --reload-rules
+sudo udevadm trigger --sysname-match=uinput
+```
+
+Without a source checkout (pip install), create the rule directly:
+
+```
+echo 'KERNEL=="uinput", SUBSYSTEM=="misc", TAG+="uaccess", OPTIONS+="static_node=uinput"' | sudo tee /etc/udev/rules.d/70-tapir-uinput.rules
+sudo udevadm control --reload-rules
+sudo udevadm trigger --sysname-match=uinput
+```
+
+The rule uses systemd's `uaccess` tag: only the user logged in at the seat gets access, not a whole group. Its file name has to sort before `73-seat-late.rules`, where udev applies `uaccess`.
+
+When access is missing, Tapir shows these instructions instead of starting.
+
+On Hyprland, Tapir never reads your keyboard. The evdev fallback for other compositors needs read access to `/dev/input/event*`, usually through the `input` group. Being in that group lets every program you run read every keystroke, passwords included, so Tapir never adds you to it. Prefer your compositor's own shortcuts (see below).
+
+## Usage
+
+Set the interval, button, click type and repeat mode, then press **Start**. The status line shows *Stopped*, *Starting in N s* or *Running*, and the counter shows the clicks of the current session. In "Repeat N times" mode the session stops on its own.
+
+The list at the top left switches the interface between English and French; the change applies immediately and is saved.
+
+The settings are locked while a session runs. When a tray is available, closing the window (the **✕** button or your compositor's close shortcut) hides it to the tray; **Quit** is in the tray menu. Without a tray, closing the window quits.
+
+## Global hotkey
+
+### Hyprland
+
+Click **Set…** next to *Hotkey* and press the combination: a key with optional Super, Ctrl, Alt and Shift, or a mouse side button (Mouse 4 / Mouse 5). Esc cancels, Backspace removes the hotkey.
+
+Tapir adds the bind to Hyprland itself with `hyprctl eval` (`hl.bind`, tagged with the description `tapir`). The hotkey works when Tapir's window is not focused, and the key press does not reach other applications.
+
+- A combination that your Hyprland config already uses is refused.
+- The bind is added again when Hyprland reloads its config, and removed when Tapir quits.
+- Hotkey starts are immediate: the countdown only applies to the window and tray.
+
+Tested with Hyprland 0.57 and a Lua config, where `hyprctl keyword` is not available.
+
+### Static bind
+
+If you prefer a permanent bind in your own config, leave Tapir's hotkey empty and add one of these.
+
+Lua config (`binds.lua`):
+
+```lua
+hl.bind("SUPER + F8", hl.dsp.exec_cmd("tapir toggle"))
+```
+
+hyprlang config (`hyprland.conf`):
+
+```
+bind = SUPER, F8, exec, tapir toggle
+```
+
+Do not set the same combination in both places, or each press toggles twice.
+
+### Other compositors
+
+Bind `tapir toggle` in your compositor's shortcut settings.
+
+Alternatively, when Tapir runs outside Hyprland and can read `/dev/input/event*` (see Permissions), **Set…** works the same way and Tapir listens to your input devices itself. It reads them without grabbing them, so the key press also reaches the focused application. Devices plugged in later are picked up within a couple of seconds.
+
+## Command line
+
+```
+tapir           open the window, or show the one already running
+tapir toggle    start or stop clicking
+tapir start     start clicking now (no countdown)
+tapir stop      stop clicking
+```
+
+Commands go to the running instance through `$XDG_RUNTIME_DIR/tapir.sock`, which only your user can reach. They exit with code 1 when no instance is running. Only one instance runs at a time.
+
+## Configuration
+
+Settings are saved to `~/.config/tapir/config.toml` (or `$XDG_CONFIG_HOME/tapir/config.toml`) on every change and loaded at startup. Invalid values fall back to their defaults.
+
+## Known limitations
+
+- Tapir clicks wherever the cursor is; it cannot move the cursor or target a window.
+- The tray is detected at startup. If Tapir starts before your bar, there is no tray icon and closing the window quits.
+- On Wayland, `tapir` or **Show** may not raise a window that is already visible: compositors limit focus stealing (Hyprland: `misc:focus_on_activate`).
+- The Hyprland conflict check compares key codes and key names. A bind written with a key name that Qt spells differently (`Prior` and `PgUp`, `Escape` and `Esc`) is not detected.
+- The managed Hyprland bind has only been tested with a Lua config.
+- When the 10 ms minimum clips the random variation, the average interval is slightly longer than the one set.
+- evdev fallback: the hotkey also reaches the focused application, and a modifier held while its device is unplugged counts as held until it is pressed again.
+- Two instances launched within the same few milliseconds can both start.
+
+## Development
+
+```
+python -m pytest
+```
+
+`tapir/engine.py` holds the click worker and the virtual mouse (no Qt), `hotkey.py` the hotkey model, Hyprland binds and evdev listener, `ipc.py` the socket and command line, `config.py` the settings file, `i18n.py` the French translations, and `ui/` the window and tray. A test checks that every text passed to `tr()` has a French translation with the same placeholders.
+
+### Releasing
+
+Set the new version in `pyproject.toml` and `pkgver` in `packaging/PKGBUILD`, commit, then push a matching tag:
+
+```
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+The *Publish* workflow runs the tests, checks that the tag matches the version in `pyproject.toml`, builds the sdist and wheel and uploads them to PyPI through trusted publishing (no API token is stored anywhere).
+
+## License
+
+MIT, see [LICENSE](https://github.com/PierreSylla/tapir-autoclicker/blob/main/LICENSE).

tapir_autoclicker-0.2.0/README.md

@@ -0,0 +1,177 @@
+# Tapir
+
+A small autoclicker for Linux Wayland desktops, with a compact Qt window.
+
+Clicks go through a virtual `uinput` mouse, so they work under any compositor. No X11 tools (xdotool, pynput, PyAutoGUI) are involved.
+
+## Features
+
+- Interval in hours, minutes, seconds and milliseconds (10 ms minimum), with an optional random variation of ± N ms
+- Left, right or middle button; single or double click
+- Repeat N times or until stopped, with a click counter
+- Optional countdown (0–10 s) when starting from the window or the tray, to give you time to place the cursor
+- Clicks at the current cursor position and never moves the cursor
+- Global start/stop hotkey: a bind managed in Hyprland, or an evdev fallback elsewhere
+- Command line and Unix socket: `tapir toggle | start | stop`
+- Tray icon coloured by state (grey stopped, amber countdown, green running)
+- English or French interface, following the system language until you pick one
+- Settings saved on every change
+
+## Installation
+
+### Arch Linux / CachyOS package
+
+```
+cd packaging
+makepkg -sif
+```
+
+The PKGBUILD builds the **last commit** of this repository: uncommitted changes, including new files that are not committed yet, are not included. `-f` rebuilds the package even when one with the same version was built before; without it, makepkg reinstalls the old file. It installs the `tapir` command, the desktop entry and the udev rule, and pacman reloads udev for you.
+
+### With pipx or pip
+
+```
+pipx install tapir-autoclicker
+```
+
+evdev ships no prebuilt wheel, so pip compiles it: you need a C compiler, the Python headers and the kernel headers (Arch: `base-devel`; Debian and Ubuntu: `build-essential python3-dev`). The udev rule and the desktop entry are not installed this way: see Permissions.
+
+### From source
+
+```
+sudo pacman -S pyside6 python-evdev python-tomli-w
+python -m tapir
+```
+
+Python 3.12 or newer. On other distributions, install PySide6, evdev and tomli-w from your package manager or with pip. From a source checkout, replace `tapir` with `python -m tapir` in the commands below.
+
+## Permissions
+
+Tapir creates its virtual mouse through `/dev/uinput` and needs write access to it. Many systems already give it to the logged-in user (Steam's `60-steam-input.rules` does, for example). To check:
+
+```
+test -w /dev/uinput && echo ok
+```
+
+If it is not writable, install the udev rule shipped with Tapir. The Arch package does it for you; from source, run:
+
+```
+scripts/setup-permissions.sh
+```
+
+The script asks for confirmation, then runs:
+
+```
+sudo install -Dm644 packaging/70-tapir-uinput.rules /etc/udev/rules.d/70-tapir-uinput.rules
+sudo udevadm control --reload-rules
+sudo udevadm trigger --sysname-match=uinput
+```
+
+Without a source checkout (pip install), create the rule directly:
+
+```
+echo 'KERNEL=="uinput", SUBSYSTEM=="misc", TAG+="uaccess", OPTIONS+="static_node=uinput"' | sudo tee /etc/udev/rules.d/70-tapir-uinput.rules
+sudo udevadm control --reload-rules
+sudo udevadm trigger --sysname-match=uinput
+```
+
+The rule uses systemd's `uaccess` tag: only the user logged in at the seat gets access, not a whole group. Its file name has to sort before `73-seat-late.rules`, where udev applies `uaccess`.
+
+When access is missing, Tapir shows these instructions instead of starting.
+
+On Hyprland, Tapir never reads your keyboard. The evdev fallback for other compositors needs read access to `/dev/input/event*`, usually through the `input` group. Being in that group lets every program you run read every keystroke, passwords included, so Tapir never adds you to it. Prefer your compositor's own shortcuts (see below).
+
+## Usage
+
+Set the interval, button, click type and repeat mode, then press **Start**. The status line shows *Stopped*, *Starting in N s* or *Running*, and the counter shows the clicks of the current session. In "Repeat N times" mode the session stops on its own.
+
+The list at the top left switches the interface between English and French; the change applies immediately and is saved.
+
+The settings are locked while a session runs. When a tray is available, closing the window (the **✕** button or your compositor's close shortcut) hides it to the tray; **Quit** is in the tray menu. Without a tray, closing the window quits.
+
+## Global hotkey
+
+### Hyprland
+
+Click **Set…** next to *Hotkey* and press the combination: a key with optional Super, Ctrl, Alt and Shift, or a mouse side button (Mouse 4 / Mouse 5). Esc cancels, Backspace removes the hotkey.
+
+Tapir adds the bind to Hyprland itself with `hyprctl eval` (`hl.bind`, tagged with the description `tapir`). The hotkey works when Tapir's window is not focused, and the key press does not reach other applications.
+
+- A combination that your Hyprland config already uses is refused.
+- The bind is added again when Hyprland reloads its config, and removed when Tapir quits.
+- Hotkey starts are immediate: the countdown only applies to the window and tray.
+
+Tested with Hyprland 0.57 and a Lua config, where `hyprctl keyword` is not available.
+
+### Static bind
+
+If you prefer a permanent bind in your own config, leave Tapir's hotkey empty and add one of these.
+
+Lua config (`binds.lua`):
+
+```lua
+hl.bind("SUPER + F8", hl.dsp.exec_cmd("tapir toggle"))
+```
+
+hyprlang config (`hyprland.conf`):
+
+```
+bind = SUPER, F8, exec, tapir toggle
+```
+
+Do not set the same combination in both places, or each press toggles twice.
+
+### Other compositors
+
+Bind `tapir toggle` in your compositor's shortcut settings.
+
+Alternatively, when Tapir runs outside Hyprland and can read `/dev/input/event*` (see Permissions), **Set…** works the same way and Tapir listens to your input devices itself. It reads them without grabbing them, so the key press also reaches the focused application. Devices plugged in later are picked up within a couple of seconds.
+
+## Command line
+
+```
+tapir           open the window, or show the one already running
+tapir toggle    start or stop clicking
+tapir start     start clicking now (no countdown)
+tapir stop      stop clicking
+```
+
+Commands go to the running instance through `$XDG_RUNTIME_DIR/tapir.sock`, which only your user can reach. They exit with code 1 when no instance is running. Only one instance runs at a time.
+
+## Configuration
+
+Settings are saved to `~/.config/tapir/config.toml` (or `$XDG_CONFIG_HOME/tapir/config.toml`) on every change and loaded at startup. Invalid values fall back to their defaults.
+
+## Known limitations
+
+- Tapir clicks wherever the cursor is; it cannot move the cursor or target a window.
+- The tray is detected at startup. If Tapir starts before your bar, there is no tray icon and closing the window quits.
+- On Wayland, `tapir` or **Show** may not raise a window that is already visible: compositors limit focus stealing (Hyprland: `misc:focus_on_activate`).
+- The Hyprland conflict check compares key codes and key names. A bind written with a key name that Qt spells differently (`Prior` and `PgUp`, `Escape` and `Esc`) is not detected.
+- The managed Hyprland bind has only been tested with a Lua config.
+- When the 10 ms minimum clips the random variation, the average interval is slightly longer than the one set.
+- evdev fallback: the hotkey also reaches the focused application, and a modifier held while its device is unplugged counts as held until it is pressed again.
+- Two instances launched within the same few milliseconds can both start.
+
+## Development
+
+```
+python -m pytest
+```
+
+`tapir/engine.py` holds the click worker and the virtual mouse (no Qt), `hotkey.py` the hotkey model, Hyprland binds and evdev listener, `ipc.py` the socket and command line, `config.py` the settings file, `i18n.py` the French translations, and `ui/` the window and tray. A test checks that every text passed to `tr()` has a French translation with the same placeholders.
+
+### Releasing
+
+Set the new version in `pyproject.toml` and `pkgver` in `packaging/PKGBUILD`, commit, then push a matching tag:
+
+```
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+The *Publish* workflow runs the tests, checks that the tag matches the version in `pyproject.toml`, builds the sdist and wheel and uploads them to PyPI through trusted publishing (no API token is stored anywhere).
+
+## License
+
+MIT, see [LICENSE](https://github.com/PierreSylla/tapir-autoclicker/blob/main/LICENSE).

tapir_autoclicker-0.2.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tapir-autoclicker"
+version = "0.2.0"
+description = "Small Wayland-friendly autoclicker with a Qt UI"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Pierre Sylla" }]
+keywords = ["autoclicker", "wayland", "hyprland", "uinput"]
+classifiers = [
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.12"
+dependencies = ["PySide6>=6.5", "evdev>=1.6", "tomli-w>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/PierreSylla/tapir-autoclicker"
+Issues = "https://github.com/PierreSylla/tapir-autoclicker/issues"
+
+[project.scripts]
+tapir = "tapir.ipc:main"
+
+[tool.setuptools.packages.find]
+include = ["tapir*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

tapir_autoclicker-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tapir_autoclicker-0.2.0/tapir/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from tapir.ipc import main
+
+sys.exit(main())

tapir_autoclicker-0.2.0/tapir/config.py

@@ -0,0 +1,57 @@
+import logging
+import os
+import tomllib
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+
+import tomli_w
+
+from tapir.engine import BUTTONS
+
+log = logging.getLogger(__name__)
+
+CONFIG_PATH = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "tapir" / "config.toml"
+
+
+@dataclass
+class Config:
+    hours: int = 0
+    minutes: int = 0
+    seconds: int = 0
+    milliseconds: int = 100
+    jitter_ms: int = 0
+    button: str = "left"
+    double_click: bool = False
+    repeat_forever: bool = True
+    repeat_count: int = 10
+    start_delay_s: int = 3
+    hotkey: str = ""
+    hotkey_label: str = ""
+    language: str = ""  # empty: follow the system
+
+
+def load(path: Path = CONFIG_PATH) -> Config:
+    try:
+        with path.open("rb") as f:
+            data = tomllib.load(f)
+    except FileNotFoundError:
+        return Config()
+    except (OSError, ValueError) as e:
+        log.warning("Ignoring unreadable config %s: %s", path, e)
+        return Config()
+    defaults = Config()
+    valid = {
+        f.name: data[f.name]
+        for f in fields(Config)
+        if type(data.get(f.name)) is type(getattr(defaults, f.name))
+    }
+    if valid.get("button") not in (None, *BUTTONS):
+        del valid["button"]
+    return Config(**valid)
+
+
+def save(config: Config, path: Path = CONFIG_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(tomli_w.dumps(asdict(config)), encoding="utf-8")
+    tmp.replace(path)

tapir_autoclicker-0.2.0/tapir/engine.py

@@ -0,0 +1,135 @@
+import math
+import random
+import threading
+import time
+from dataclasses import dataclass
+from enum import StrEnum
+
+from evdev import UInput, ecodes
+
+MIN_INTERVAL_MS = 10
+DOUBLE_CLICK_GAP_S = 0.04
+UINPUT_NAME = "tapir-virtual-mouse"
+BUTTON_CODES = {"left": ecodes.BTN_LEFT, "right": ecodes.BTN_RIGHT, "middle": ecodes.BTN_MIDDLE}
+BUTTONS = tuple(BUTTON_CODES)
+
+
+class State(StrEnum):
+    STOPPED = "stopped"
+    PENDING = "pending"
+    RUNNING = "running"
+
+
+@dataclass(frozen=True)
+class ClickSettings:
+    interval_ms: int
+    button: str = "left"
+    double: bool = False
+    repeat: int | None = None  # None = until stopped
+    jitter_ms: int = 0
+
+
+def total_ms(hours: int = 0, minutes: int = 0, seconds: int = 0, milliseconds: int = 0) -> int:
+    return ((hours * 60 + minutes) * 60 + seconds) * 1000 + milliseconds
+
+
+def gap_range_ms(interval_ms: int, jitter_ms: int = 0) -> tuple[int, int]:
+    base = max(interval_ms, MIN_INTERVAL_MS)
+    return max(base - jitter_ms, MIN_INTERVAL_MS), base + jitter_ms
+
+
+def gap_ms(interval_ms: int, jitter_ms: int = 0) -> int:
+    return random.randint(*gap_range_ms(interval_ms, jitter_ms))
+
+
+class UInputEmitter:
+    """Virtual mouse; clicks land wherever the compositor's cursor is."""
+
+    def __init__(self):
+        # REL axes are never used but make libinput classify the device as a pointer.
+        self._ui = UInput(
+            {ecodes.EV_KEY: list(BUTTON_CODES.values()), ecodes.EV_REL: [ecodes.REL_X, ecodes.REL_Y, ecodes.REL_WHEEL]},
+            name=UINPUT_NAME,
+        )
+
+    def press(self, button: str) -> None:
+        self._ui.write(ecodes.EV_KEY, BUTTON_CODES[button], 1)
+        self._ui.syn()
+
+    def release(self, button: str) -> None:
+        self._ui.write(ecodes.EV_KEY, BUTTON_CODES[button], 0)
+        self._ui.syn()
+
+    def close(self) -> None:
+        # The kernel drops releases for buttons that are not down, so releasing everything is safe.
+        for code in BUTTON_CODES.values():
+            self._ui.write(ecodes.EV_KEY, code, 0)
+        self._ui.syn()
+        self._ui.close()
+
+
+class Clicker:
+    """Click worker thread; callbacks run on the worker thread."""
+
+    def __init__(self, emitter, on_state=None, on_count=None):
+        self._emitter = emitter
+        self._on_state = on_state or (lambda state, countdown=0: None)
+        self._on_count = on_count or (lambda count: None)
+        self._thread: threading.Thread | None = None
+        self._stop = threading.Event()
+
+    @property
+    def active(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    def start(self, settings: ClickSettings, start_delay_s: float = 0) -> None:
+        if self.active:
+            return
+        self._stop = threading.Event()
+        self._thread = threading.Thread(
+            target=self._run, args=(settings, start_delay_s, self._stop), name="tapir-clicker", daemon=True
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join()
+
+    def _run(self, settings: ClickSettings, start_delay_s: float, stop: threading.Event) -> None:
+        try:
+            if self._countdown(start_delay_s, stop):
+                return
+            self._on_state(State.RUNNING)
+            self._click_loop(settings, stop)
+        finally:
+            self._on_state(State.STOPPED)
+
+    def _countdown(self, seconds: float, stop: threading.Event) -> bool:
+        end = time.monotonic() + seconds
+        while (left := end - time.monotonic()) > 0:
+            whole = math.ceil(left)
+            self._on_state(State.PENDING, whole)
+            if stop.wait(left - whole + 1):
+                return True
+        return stop.is_set()
+
+    def _click_loop(self, settings: ClickSettings, stop: threading.Event) -> None:
+        count = 0
+        next_at = time.monotonic()
+        while settings.repeat is None or count < settings.repeat:
+            if stop.wait(max(0.0, next_at - time.monotonic())):
+                return
+            self._click(settings, stop)
+            count += 1
+            self._on_count(count)
+            # After a stall (suspend, overload) resume from now instead of firing a burst of late clicks.
+            gap = gap_ms(settings.interval_ms, settings.jitter_ms) / 1000
+            next_at = max(next_at + gap, time.monotonic())
+
+    def _click(self, settings: ClickSettings, stop: threading.Event) -> None:
+        self._emitter.press(settings.button)
+        self._emitter.release(settings.button)
+        if settings.double and not stop.wait(DOUBLE_CLICK_GAP_S):
+            self._emitter.press(settings.button)
+            self._emitter.release(settings.button)