Merge remote-tracking branch 'origin/main'

# Conflicts:
#	pom.xml

.drone.yml

@@ -12,19 +12,19 @@ trigger:
 steps:
   # test if it compiles correctly
   - name: build
-    image: maven:3-eclipse-temurin-21
+    image: maven:3-eclipse-temurin-25
     commands:
       - mvn verify --no-transfer-progress -DskipTests=true -Dmaven.javadoc.skip=true -B -V
 
   # run unit tests
   - name: test
-    image: maven:3-eclipse-temurin-21
+    image: maven:3-eclipse-temurin-25
     commands:
       - mvn test --no-transfer-progress -B -V
 
   # run code analysis
   - name: code-analysis
-    image: maven:3-eclipse-temurin-21
+    image: maven:3-eclipse-temurin-25
     commands:
       - mvn sonar:sonar --no-transfer-progress -Dsonar.projectKey=$SONAR_PROJECT_KEY -Dsonar.host.url=$SONAR_INSTANCE_URL -Dsonar.token=$SONAR_LOGIN_KEY -B -V
     environment:
@@ -55,7 +55,7 @@ steps:
 
   # upload to maven repository
   - name: maven-deploy
-    image: maven:3-eclipse-temurin-21
+    image: maven:3-eclipse-temurin-25
     commands:
       - mvn deploy --no-transfer-progress -DskipTests=true -Dmaven.javadoc.skip=true -B -V -gs settings.xml -Dmaven.repo.username=$MAVEN_REPO_USERNAME -Dmaven.repo.password=$MAVEN_REPO_PASSWORD
     environment:

pom.xml

@@ -9,8 +9,7 @@
     <version>0.0.5-SNAPSHOT</version>
 
     <properties>
-        <maven.compiler.source>21</maven.compiler.source>
-        <maven.compiler.target>21</maven.compiler.target>
+        <maven.compiler.release>25</maven.compiler.release>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     </properties>
 
@@ -18,13 +17,13 @@
         <dependency>
             <groupId>org.apache.logging.log4j</groupId>
             <artifactId>log4j-api</artifactId>
-            <version>2.24.3</version>
+            <version>2.26.1</version>
         </dependency>
 
         <dependency>
             <groupId>org.apache.logging.log4j</groupId>
             <artifactId>log4j-core</artifactId>
-            <version>2.24.3</version>
+            <version>2.26.1</version>
         </dependency>
 
         <dependency>
@@ -32,6 +31,13 @@
             <artifactId>jnativehook</artifactId>
             <version>2.2.2</version>
         </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>6.1.3</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <distributionManagement>
@@ -49,6 +55,12 @@
 
     <build>
         <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <version>3.6.0</version>
+            </plugin>
+
             <plugin>
                 <groupId>org.sonarsource.scanner.maven</groupId>
                 <artifactId>sonar-maven-plugin</artifactId>
@@ -98,4 +110,79 @@
         </pluginRepository>
     </pluginRepositories>
 
+    <profiles>
+        <!-- builds a native .app bundle. jpackage can only target the os it runs on:
+             run this profile on macos with `mvn clean package -Pmac-app` -->
+        <profile>
+            <id>mac-app</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-resources-plugin</artifactId>
+                        <version>3.5.0</version>
+                        <executions>
+                            <execution>
+                                <id>stage-jpackage-input</id>
+                                <phase>package</phase>
+                                <goals>
+                                    <goal>copy-resources</goal>
+                                </goals>
+                                <configuration>
+                                    <outputDirectory>${project.build.directory}/jpackage-input</outputDirectory>
+                                    <resources>
+                                        <resource>
+                                            <directory>${project.build.directory}</directory>
+                                            <includes>
+                                                <include>${project.build.finalName}-jar-with-dependencies.jar</include>
+                                            </includes>
+                                        </resource>
+                                    </resources>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+
+                    <plugin>
+                        <groupId>org.codehaus.mojo</groupId>
+                        <artifactId>exec-maven-plugin</artifactId>
+                        <version>3.6.4</version>
+                        <executions>
+                            <execution>
+                                <id>jpackage-app-image</id>
+                                <phase>package</phase>
+                                <goals>
+                                    <goal>exec</goal>
+                                </goals>
+                                <configuration>
+                                    <executable>${java.home}/bin/jpackage</executable>
+                                    <arguments>
+                                        <argument>--type</argument>
+                                        <argument>app-image</argument>
+                                        <argument>--name</argument>
+                                        <argument>${project.artifactId}</argument>
+                                        <argument>--dest</argument>
+                                        <argument>${project.build.directory}/jpackage</argument>
+                                        <argument>--input</argument>
+                                        <argument>${project.build.directory}/jpackage-input</argument>
+                                        <argument>--main-jar</argument>
+                                        <argument>${project.build.finalName}-jar-with-dependencies.jar</argument>
+                                        <argument>--main-class</argument>
+                                        <argument>wtf.beatrice.autosqueal.Main</argument>
+                                        <argument>--java-options</argument>
+                                        <argument>--enable-native-access=ALL-UNNAMED</argument>
+                                        <argument>--mac-package-identifier</argument>
+                                        <argument>wtf.beatrice.autosqueal</argument>
+                                        <argument>--mac-package-name</argument>
+                                        <argument>autosqueal</argument>
+                                    </arguments>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+
 </project>

readme.md

@@ -8,6 +8,8 @@
   
   
 *little java tool to automatically perform mouse actions*  
+
+*once started, it only acts when you are away: it detects your activity and pauses itself while you are using the machine, so it never fights you for the mouse.*  
   
 ## supported systems  
 | system    | support    |
@@ -18,7 +20,7 @@
   
 ## building  
 **required tools**  
- - java 21 sdk  
+ - java 25 sdk  
  - git  
  - maven  
   
@@ -26,7 +28,11 @@
  1. clone the official repository linked below using `git clone`.  
  2. `cd` into the directory and run `mvn clean package`.  
  3. you will find a runnable jar with dependencies in the `target/` folder.  
- 4. run the built jar file with `java -jar target/autosqueal-*-dependencies.jar`.
+ 4. run the built jar file with `java -jar target/autosqueal-*-jar-with-dependencies.jar`.
+
+**macos .app bundle**  
+ - on macos, run `mvn clean package -Pmac-app`: you will find `autosqueal.app` in `target/jpackage/`.  
+ - the first time you run it, grant it the device control and data access permission (called "accessibility" on older macos versions) and the screen recording one, in system settings, like any other java app.
   
 ## support  
 | category            | info                                                          |

src/main/java/wtf/beatrice/autosqueal/Main.java

@@ -7,6 +7,9 @@ import org.apache.logging.log4j.Logger;
 import wtf.beatrice.autosqueal.listener.KeyPressListener;
 import wtf.beatrice.autosqueal.ui.MainWindow;
 
+import javax.swing.*;
+import javax.swing.UnsupportedLookAndFeelException;
+
 public class Main {
 
     private static final Logger LOGGER = LogManager.getLogger(Main.class);
@@ -15,22 +18,53 @@ public class Main {
     public static void main(String[] args) {
         LOGGER.info("Hello world!");
 
-        registerJNativeHook();
-        mainWindow.init();
+        useSystemLookAndFeel();
+        boolean hookRegistered = registerJNativeHook();
+
+        // all Swing components must be created and updated on the EDT
+        SwingUtilities.invokeLater(() -> {
+            mainWindow.init();
+            if (!hookRegistered) {
+                mainWindow.showPermissionsHelp();
+            }
+        });
     }
 
-    private static void registerJNativeHook() {
+    private static void useSystemLookAndFeel() {
+        try {
+            UIManager.setLookAndFeel(UIManager.getSystemLookAndFeelClassName());
+        } catch (ReflectiveOperationException | UnsupportedLookAndFeelException ex) {
+            LOGGER.warn("Could not set the system look and feel, using the default one", ex);
+        }
+    }
+
+    public static boolean registerJNativeHook() {
         LOGGER.info("Registering jnativehook library...");
         try {
             GlobalScreen.registerNativeHook();
             GlobalScreen.addNativeKeyListener(new KeyPressListener());
             LOGGER.info("Successfully registered jnativehook library!");
+            return true;
         }
         catch (NativeHookException ex) {
-            LOGGER.error("There was a problem registering the native hook.");
-            LOGGER.error(ex.getMessage());
+            LOGGER.error("There was a problem registering the native hook.", ex);
 
-            System.exit(1);
+            // without the accessibility permission the hotkey cannot be
+            // registered and the mouse cannot be moved either: the app would
+            // look alive but do nothing. don't exit: keep the window and the
+            // tray icon usable, and tell the user what is missing.
+            return false;
+        }
+    }
+
+    public static void unregisterJNativeHook() {
+        try {
+            GlobalScreen.unregisterNativeHook();
+            LOGGER.info("Successfully unregistered jnativehook library!");
+        }
+        catch (NativeHookException ex) {
+            LOGGER.error("There was a problem unregistering the native hook.");
+            LOGGER.error(ex.getMessage());
         }
     }
 
@@ -38,4 +72,4 @@ public class Main {
         return mainWindow;
     }
 
-}
+}

src/main/java/wtf/beatrice/autosqueal/controls/CursorMover.java

@@ -7,66 +7,77 @@ import wtf.beatrice.autosqueal.util.RunnerUtil;
 import java.awt.*;
 import java.security.SecureRandom;
 import java.util.Random;
-import java.util.Timer;
-import java.util.TimerTask;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.RejectedExecutionException;
+import java.util.function.BooleanSupplier;
 
-public class CursorMover extends TimerTask
+/**
+ * Periodically starts a new movement of the mouse cursor to a random position,
+ * or to the top-right corner of the screen for a double click.
+ *
+ * The movements only happen when the user is away: while the user is actively
+ * using the machine, they are skipped, so the app never fights for the mouse.
+ *
+ * The movement itself is executed by a {@link SingleStepMovementTask}, which
+ * runs on its own virtual thread until it reaches its destination.
+ */
+public class CursorMover implements Runnable
 {
-
     private static final Logger LOGGER = LogManager.getLogger(CursorMover.class);
-    private final Random random;
 
     private static final int LOOPS_BEFORE_CLICK = 5;
 
+    private final Random random = new SecureRandom();
+    private final ExecutorService movementExecutor;
+    private final RobotMouseTracker robotTracker;
+    private final BooleanSupplier isUserAway;
+
     private int iteration = 0;
 
-    public CursorMover() {
-        random = new SecureRandom();
+    public CursorMover(ExecutorService movementExecutor, RobotMouseTracker robotTracker, BooleanSupplier isUserAway) {
+        this.movementExecutor = movementExecutor;
+        this.robotTracker = robotTracker;
+        this.isUserAway = isUserAway;
     }
 
     @Override
     public void run() {
 
-        int currentX = MouseInfo.getPointerInfo().getLocation().x;
-        int currentY = MouseInfo.getPointerInfo().getLocation().y;
+        if (!isUserAway.getAsBoolean()) {
+            LOGGER.debug("User is present, skipping movement");
+            return;
+        }
 
-        LOGGER.info("Starting coordinates: {}, {}", currentX, currentY);
+        Point location = MouseInfo.getPointerInfo().getLocation();
+        LOGGER.info("Starting coordinates: {}, {}", location.x, location.y);
 
         int destX;
         int destY;
-
-        SingleStepMovementTask singleStepMovementTask;
+        boolean click;
 
         if (iteration == LOOPS_BEFORE_CLICK) {
             destX = RunnerUtil.SCREEN_WIDTH - 5;
             destY = 5;
-
-            try {
-                singleStepMovementTask = new SingleStepMovementTask(destX, destY, true);
-            } catch (AWTException e) {
-                LOGGER.error(e);
-                return;
-            }
+            click = true;
 
             iteration = 0;
         } else {
             destX = random.nextInt(RunnerUtil.SCREEN_WIDTH);
             destY = random.nextInt(RunnerUtil.SCREEN_HEIGHT);
-
-            try {
-                singleStepMovementTask = new SingleStepMovementTask(destX, destY, false);
-            } catch (AWTException e) {
-                LOGGER.error(e);
-                return;
-            }
+            click = false;
 
             iteration++;
         }
 
         LOGGER.info("Destination coordinates: {}, {}", destX, destY);
 
-        Timer timer = new Timer();
-        timer.schedule(singleStepMovementTask, 0L, 2L);
-
+        try {
+            SingleStepMovementTask movement = new SingleStepMovementTask(robotTracker, destX, destY, click);
+            movementExecutor.execute(movement);
+        } catch (AWTException ex) {
+            LOGGER.error("Could not start movement task", ex);
+        } catch (RejectedExecutionException ex) {
+            LOGGER.debug("Movement not started: automation is shutting down");
+        }
     }
-}
+}

src/main/java/wtf/beatrice/autosqueal/controls/RobotMouseTracker.java

@@ -0,0 +1,37 @@
+package wtf.beatrice.autosqueal.controls;
+
+/**
+ * Keeps track of the mouse movements the app itself performs, so that other
+ * components (like the away detection) can tell them apart from the user's.
+ *
+ * Written by the movement tasks, read by whoever needs to know.
+ */
+public class RobotMouseTracker {
+
+    private volatile boolean moving = false;
+    private volatile int lastX = Integer.MIN_VALUE;
+    private volatile int lastY = Integer.MIN_VALUE;
+
+    /** Marks the start of a movement performed by the app. */
+    public void moveStarted() {
+        moving = true;
+    }
+
+    /**
+     * Marks the end of a movement performed by the app, which left the cursor
+     * at the given coordinates.
+     */
+    public void moveEnded(int x, int y) {
+        lastX = x;
+        lastY = y;
+        moving = false;
+    }
+
+    public boolean isMoving() {
+        return moving;
+    }
+
+    public boolean isLastPosition(int x, int y) {
+        return x == lastX && y == lastY;
+    }
+}

src/main/java/wtf/beatrice/autosqueal/controls/SingleStepMovementTask.java

@@ -5,113 +5,166 @@ import org.apache.logging.log4j.Logger;
 
 import java.awt.*;
 import java.awt.event.InputEvent;
-import java.util.TimerTask;
 
-public class SingleStepMovementTask extends TimerTask {
+/**
+ * Moves the mouse cursor towards a destination one small step at a time.
+ *
+ * Runs on its own virtual thread: it mostly sleeps between steps, so blocking
+ * it is free. When it gets to its destination, it can optionally perform a
+ * double click, with the pacing the app has always used.
+ *
+ * All the movements it performs are reported to the {@link RobotMouseTracker},
+ * so that the away detection can tell them apart from the user's.
+ */
+public class SingleStepMovementTask implements Runnable {
 
     private static final Logger LOGGER = LogManager.getLogger(SingleStepMovementTask.class);
 
-    final int destX;
-    final int destY;
-    final Robot robot;
+    /** Delay between two consecutive cursor steps, in milliseconds. */
+    private static final long STEP_DELAY_MILLISECONDS = 2L;
 
-    float currentX;
-    float currentY;
+    private final RobotMouseTracker robotTracker;
+    private final Robot robot;
+    private final int destX;
+    private final int destY;
+    private final boolean click;
 
-    float stepX = 1;
-    float stepY = 1;
-    boolean isRunning = true;
-    boolean click;
+    private float currentX;
+    private float currentY;
+    private float stepX;
+    private float stepY;
 
+    public SingleStepMovementTask(RobotMouseTracker robotTracker, int destinationX, int destinationY, boolean click) throws AWTException {
 
-    public SingleStepMovementTask(int destinationX, int destinationY, boolean click) throws AWTException {
-
+        this.robotTracker = robotTracker;
+        this.destX = destinationX;
+        this.destY = destinationY;
         this.click = click;
 
-        currentX = MouseInfo.getPointerInfo().getLocation().x;
-        currentY = MouseInfo.getPointerInfo().getLocation().y;
+        Point location = MouseInfo.getPointerInfo().getLocation();
+        this.currentX = location.x;
+        this.currentY = location.y;
 
-        destX = destinationX;
-        destY = destinationY;
+        int lengthX = Math.round(Math.abs(currentX - destX));
+        int lengthY = Math.round(Math.abs(currentY - destY));
 
-        int lengthX;
-        int lengthY;
-
-        lengthX = Math.round(Math.abs(currentX - destX));
-        lengthY = Math.round(Math.abs(currentY - destY));
-
-        if(lengthX > lengthY) {
-            stepX = lengthX / (float) lengthY;
-        }
-
-        if(lengthY > lengthX) {
-            stepY = lengthY / (float) lengthX;
-        }
+        this.stepX = computeStepX(lengthX, lengthY);
+        this.stepY = computeStepY(lengthX, lengthY);
 
         LOGGER.info("Dest: [{}, {}], Curr: [{}, {}]", destX, destY, currentX, currentY);
-        LOGGER.info("Len: [{}, {}]", lengthX, lengthY);
         LOGGER.info("Step: [{}, {}]", stepX, stepY);
 
-        robot = new Robot();
-
+        this.robot = new Robot();
     }
 
     @Override
     public void run() {
-        if(Math.abs(currentX - destX) < 1) {
-            stepX = currentX - destX;
-        }
 
-        if(Math.abs(currentY - destY) < 1) {
-            stepY = currentY - destY;
-        }
+        // any position change from here on is the app's doing
+        robotTracker.moveStarted();
 
-        if(destX == Math.round(currentX) || destY == Math.round(currentY)) {
+        try {
+            while (!hasReachedDestination()) {
+                // when less than a full step is left, move exactly what is
+                // left, so that both axes always land on their destination
+                stepX = adjustedStep(currentX, destX, stepX);
+                stepY = adjustedStep(currentY, destY, stepY);
 
-            if (click) {
-                try {
-                    Thread.sleep(500);
-                    robot.mousePress(InputEvent.BUTTON1_DOWN_MASK);
-                    Thread.sleep(200);
-                    robot.mouseRelease(InputEvent.BUTTON1_DOWN_MASK);
-                    Thread.sleep(500);
-                    robot.mousePress(InputEvent.BUTTON1_DOWN_MASK);
-                    Thread.sleep(200);
-                    robot.mouseRelease(InputEvent.BUTTON1_DOWN_MASK);
-                    Thread.sleep(200);
-                } catch (InterruptedException e) {
-                    LOGGER.error(e);
-                    Thread.currentThread().interrupt();
-                }
+                currentX = advance(currentX, destX, stepX);
+                currentY = advance(currentY, destY, stepY);
+
+                robot.mouseMove(Math.round(currentX), Math.round(currentY));
+
+                Thread.sleep(STEP_DELAY_MILLISECONDS);
             }
 
-            LOGGER.info("Reached destination, stopping mover timer");
-            LOGGER.info("Dest: [{}, {}], Curr: [{}, {}]", destX, destY, currentX, currentY);
-            isRunning = false;
-            this.cancel();
-            return;
+            onDestinationReached();
+        } catch (InterruptedException ex) {
+            // the movement was interrupted: the automation was stopped, so
+            // just end the movement here
+            Thread.currentThread().interrupt();
+            LOGGER.debug("Movement interrupted");
+            robotTracker.moveEnded(Math.round(currentX), Math.round(currentY));
+        } catch (RuntimeException ex) {
+            LOGGER.error("Unexpected error while moving the cursor", ex);
+            robotTracker.moveEnded(Math.round(currentX), Math.round(currentY));
         }
-
-        if(currentX > destX) {
-            currentX -= stepX;
-        }
-
-        if(currentY > destY) {
-            currentY -= stepY;
-        }
-
-        if(currentX < destX) {
-            currentX += stepX;
-        }
-
-        if(currentY < destY) {
-            currentY += stepY;
-        }
-
-        robot.mouseMove(Math.round(currentX), Math.round(currentY));
     }
 
-    public boolean isRunning() {
-        return isRunning;
+    private boolean hasReachedDestination() {
+        return Math.round(currentX) == destX && Math.round(currentY) == destY;
     }
-}
+
+    private void onDestinationReached() throws InterruptedException {
+        LOGGER.info("Reached destination [{}, {}], stopping mover", destX, destY);
+
+        robotTracker.moveEnded(destX, destY);
+
+        if (click) {
+            performClickSequence();
+        }
+    }
+
+    /**
+     * Performs a double click with the same pacing the app has always used:
+     * press at +500ms, release at +700ms, press at +1200ms, release at +1400ms.
+     */
+    private void performClickSequence() throws InterruptedException {
+        Thread.sleep(500L);
+        robot.mousePress(InputEvent.BUTTON1_DOWN_MASK);
+        Thread.sleep(200L);
+        robot.mouseRelease(InputEvent.BUTTON1_DOWN_MASK);
+        Thread.sleep(500L);
+        robot.mousePress(InputEvent.BUTTON1_DOWN_MASK);
+        Thread.sleep(200L);
+        robot.mouseRelease(InputEvent.BUTTON1_DOWN_MASK);
+    }
+
+    /**
+     * Step to take on the X axis so that both axes reach their destination
+     * after the same number of steps. Returns 0 when there is no movement to make.
+     */
+    static float computeStepX(int lengthX, int lengthY) {
+        if (lengthX == 0) {
+            return 0.0f;
+        }
+        if (lengthX >= lengthY) {
+            return 1.0f;
+        }
+        return lengthX / (float) lengthY;
+    }
+
+    /**
+     * Step to take on the Y axis so that both axes reach their destination
+     * after the same number of steps. Returns 0 when there is no movement to make.
+     */
+    static float computeStepY(int lengthX, int lengthY) {
+        if (lengthY == 0) {
+            return 0.0f;
+        }
+        if (lengthY > lengthX) {
+            return 1.0f;
+        }
+        return lengthY / (float) lengthX;
+    }
+
+    /**
+     * When less than a whole step is left to travel, move exactly what is left
+     * instead of a whole step, so that the cursor doesn't overshoot the destination.
+     */
+    static float adjustedStep(float current, float destination, float step) {
+        float remaining = Math.abs(current - destination);
+        return remaining < 1.0f ? remaining : step;
+    }
+
+    /** Moves current towards destination by step, in the right direction. */
+    static float advance(float current, float destination, float step) {
+        if (current > destination) {
+            return current - step;
+        }
+        if (current < destination) {
+            return current + step;
+        }
+        return current;
+    }
+}

src/main/java/wtf/beatrice/autosqueal/listener/CursorMoveListener.java

@@ -2,51 +2,86 @@ package wtf.beatrice.autosqueal.listener;
 
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import wtf.beatrice.autosqueal.controls.RobotMouseTracker;
 
 import java.awt.*;
-import java.util.TimerTask;
+import java.util.function.Supplier;
 
-public class CursorMoveListener extends TimerTask {
-
-    private int oldX;
-    private int oldY;
-
-    private int loops;
-    private boolean isUserAway;
+/**
+ * Watches the cursor position and tracks whether the user is away: if the cursor
+ * stays still for long enough — ignoring the movements the app performs on its
+ * own — the user is considered away.
+ */
+public class CursorMoveListener implements Runnable {
 
     private static final Logger LOGGER = LogManager.getLogger(CursorMoveListener.class);
 
+    /** Number of consecutive still polls after which the user is considered away. */
+    private static final int LOOPS_BEFORE_AWAY = 30;
 
-    public CursorMoveListener() {
-        oldX = 0;
-        oldY = 0;
-        loops = 0;
+    private final RobotMouseTracker robotTracker;
+    private final Supplier<Point> currentPosition;
+
+    private int lastSeenX;
+    private int lastSeenY;
+    private boolean firstPoll = true;
+    private int loops = 0;
+    private volatile boolean userAway = false;
+
+    public CursorMoveListener(RobotMouseTracker robotTracker) {
+        this(robotTracker, () -> MouseInfo.getPointerInfo().getLocation());
+    }
+
+    CursorMoveListener(RobotMouseTracker robotTracker, Supplier<Point> currentPosition) {
+        this.robotTracker = robotTracker;
+        this.currentPosition = currentPosition;
     }
 
     @Override
     public void run() {
-        int newX = MouseInfo.getPointerInfo().getLocation().x;
-        int newY = MouseInfo.getPointerInfo().getLocation().y;
 
-        if(newX != oldX || newY != oldY) {
-            // cursor has been moved
+        Point location = currentPosition.get();
+
+        if (firstPoll) {
+            // seed the comparison baseline, so that the first poll is not
+            // mistaken for a movement
+            firstPoll = false;
+            lastSeenX = location.x;
+            lastSeenY = location.y;
+            return;
+        }
+
+        boolean positionChanged = location.x != lastSeenX || location.y != lastSeenY;
+        boolean userMoved = positionChanged && !isAppMovement(location);
+
+        if (userMoved) {
+            if (userAway) {
+                LOGGER.info("User is no longer away!");
+            }
             loops = 0;
-            LOGGER.info("User is no longer away!");
-        } else {
-            if (loops < 30) {
-                loops++;
-            } else {
+        } else if (loops < LOOPS_BEFORE_AWAY) {
+            loops++;
+            if (loops == LOOPS_BEFORE_AWAY) {
                 LOGGER.info("User is away!");
             }
         }
 
-        isUserAway = loops >= 30;
+        userAway = loops >= LOOPS_BEFORE_AWAY;
 
-        oldX = newX;
-        oldY = newY;
+        lastSeenX = location.x;
+        lastSeenY = location.y;
+    }
+
+    /**
+     * Whether a position change was (most likely) caused by the app itself:
+     * either a movement is currently in progress, or the cursor is exactly
+     * where the app last left it.
+     */
+    private boolean isAppMovement(Point location) {
+        return robotTracker.isMoving() || robotTracker.isLastPosition(location.x, location.y);
     }
 
     public boolean isUserAway() {
-        return isUserAway;
+        return userAway;
     }
-}
+}

src/main/java/wtf/beatrice/autosqueal/listener/KeyPressListener.java

@@ -1,7 +1,5 @@
 package wtf.beatrice.autosqueal.listener;
 
-import com.github.kwhat.jnativehook.GlobalScreen;
-import com.github.kwhat.jnativehook.NativeHookException;
 import com.github.kwhat.jnativehook.keyboard.NativeKeyEvent;
 import com.github.kwhat.jnativehook.keyboard.NativeKeyListener;
 import org.apache.logging.log4j.LogManager;
@@ -14,46 +12,40 @@ import java.util.List;
 public class KeyPressListener implements NativeKeyListener
 {
     private static final Logger LOGGER = LogManager.getLogger(KeyPressListener.class);
-    private static final List<Integer> pressedKeysIds = new ArrayList<>();
+    private final List<Integer> pressedKeys = new ArrayList<>();
 
     @Override
     public void nativeKeyPressed(NativeKeyEvent e) {
-        String key = NativeKeyEvent.getKeyText(e.getKeyCode());
-        LOGGER.info("Key Pressed: {}", key);
-
-        if (e.getKeyCode() == NativeKeyEvent.VC_ESCAPE) {
-            try {
-                GlobalScreen.unregisterNativeHook();
-            } catch (NativeHookException nativeHookException) {
-                LOGGER.error("Failed to unregister native hook", nativeHookException);
-            }
+        // the OS fires repeated "press" events while a key is being held down; ignore them,
+        // otherwise holding the toggle combo down would rapidly toggle the app on and off
+        if (pressedKeys.contains(e.getKeyCode())) {
+            return;
         }
 
-        pressedKeysIds.add(e.getKeyCode());
+        pressedKeys.add(e.getKeyCode());
+        LOGGER.info("Key Pressed: {}", NativeKeyEvent.getKeyText(e.getKeyCode()));
 
-        handlePressedKeys();
-    }
+        if (e.getKeyCode() == NativeKeyEvent.VC_ESCAPE) {
+            Main.unregisterJNativeHook();
+        }
 
-    @Override
-    public void nativeKeyReleased(NativeKeyEvent e) {
-        String key = NativeKeyEvent.getKeyText(e.getKeyCode());
-        LOGGER.info("Key Released: {}", key);
-
-        pressedKeysIds.remove((Integer) e.getKeyCode());
-
-        handlePressedKeys();
-    }
-
-    private void handlePressedKeys() {
-        if (pressedKeysIds.contains(NativeKeyEvent.VC_ALT) &&
-        pressedKeysIds.contains(NativeKeyEvent.VC_CONTROL)) {
-
-            StringBuilder keys = new StringBuilder();
-            pressedKeysIds.forEach(keyCode -> keys.append("[").append(NativeKeyEvent.getKeyText(keyCode)).append("]"));
-
-            LOGGER.warn("Received shutdown keystroke: {}", keys);
+        // toggle only when the second key of the combo is pressed down: not only does this
+        // fire exactly once per combo, but it also avoids toggling when any other key is
+        // pressed or released while ctrl+alt happen to be held down
+        if ((e.getKeyCode() == NativeKeyEvent.VC_CONTROL && pressedKeys.contains(NativeKeyEvent.VC_ALT))
+                || (e.getKeyCode() == NativeKeyEvent.VC_ALT && pressedKeys.contains(NativeKeyEvent.VC_CONTROL))) {
+            LOGGER.warn("Received shutdown keystroke: [{}][{}]",
+                    NativeKeyEvent.getKeyText(NativeKeyEvent.VC_CONTROL),
+                    NativeKeyEvent.getKeyText(NativeKeyEvent.VC_ALT));
 
             Main.getMainWindow().toggleRunning();
         }
     }
-}
+
+    @Override
+    public void nativeKeyReleased(NativeKeyEvent e) {
+        LOGGER.info("Key Released: {}", NativeKeyEvent.getKeyText(e.getKeyCode()));
+
+        pressedKeys.remove((Integer) e.getKeyCode());
+    }
+}

src/main/java/wtf/beatrice/autosqueal/ui/MainWindow.java

@@ -3,15 +3,23 @@ package wtf.beatrice.autosqueal.ui;
 import com.github.kwhat.jnativehook.keyboard.NativeKeyEvent;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import wtf.beatrice.autosqueal.Main;
 import wtf.beatrice.autosqueal.controls.CursorMover;
+import wtf.beatrice.autosqueal.controls.RobotMouseTracker;
 import wtf.beatrice.autosqueal.listener.CursorMoveListener;
 import wtf.beatrice.autosqueal.util.RunnerUtil;
 import wtf.beatrice.autosqueal.util.SystemUtil;
 
 import javax.swing.*;
 import java.awt.*;
+import java.awt.event.WindowAdapter;
+import java.awt.event.WindowEvent;
 import java.awt.image.BufferedImage;
-import java.util.Timer;
+import java.io.IOException;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
 
 public class MainWindow
 {
@@ -20,22 +28,40 @@ public class MainWindow
     private static final int WINDOW_HEIGHT = 700;
     private static final int WINDOW_WIDTH = 800;
 
-    private Timer timerRunner = new Timer();
-    private CursorMover cursorMover = new CursorMover();
-    private Button toggleButton;
+    private static final long AUTOMATION_START_DELAY_SECONDS = 1L;
+    private static final long AWAY_POLL_INTERVAL_SECONDS = 1L;
 
+    private final JFrame frame = new JFrame();
+    private JButton toggleButton;
+
+    private ScheduledExecutorService periodicScheduler;
+    private ExecutorService movementExecutor;
+    private CursorMover cursorMover;
+
+    private TrayIcon trayIcon;
+    private MenuItem trayToggleItem;
+
+    /**
+     * Builds and shows the main window, and starts the automation.
+     * Must be called on the EDT.
+     */
     public void init() {
 
-        JFrame frame = new JFrame();
         frame.setSize(new Dimension(WINDOW_WIDTH, WINDOW_HEIGHT));
         frame.setTitle("autosqueal");
         frame.setResizable(false);
+        frame.setDefaultCloseOperation(WindowConstants.EXIT_ON_CLOSE);
+        frame.addWindowListener(new WindowAdapter() {
+            @Override
+            public void windowClosing(WindowEvent e) {
+                cleanup();
+            }
+        });
 
-        toggleButton = new Button();
+        toggleButton = new JButton();
         toggleButton.setBounds(new Rectangle((WINDOW_WIDTH / 2) - 60, WINDOW_HEIGHT - 60, 120, 30));
         toggleButton.addActionListener(e -> toggleRunning());
         frame.add(toggleButton);
-        toggleRunning();
 
         int bordersPx = 10;
         int rescaleRateo = ((WINDOW_WIDTH - (2 * bordersPx)) * 100) / RunnerUtil.SCREEN_WIDTH;
@@ -50,9 +76,15 @@ public class MainWindow
         timestampLabel.setBounds(new Rectangle(bordersPx, bordersPx + rescaleHeight + bordersPx, 100, 30));
         frame.add(timestampLabel);
 
-
         frame.setLayout(null);
         frame.setVisible(true);
+
+        if (SystemTray.isSupported()) {
+            addTrayIcon();
+        }
+
+        startAutomation();
+        updateToggleLabel();
     }
 
     private Image getScreenCapture(int rescaleWidth, int rescaleHeight) {
@@ -82,56 +114,204 @@ public class MainWindow
         return null;
     }
 
-    public BufferedImage getBufferedImage(Image img) {
-        if (img instanceof BufferedImage image)
-        {
-            return image;
+    /**
+     * Adds a menu bar icon with a toggle entry and a quit entry, so the
+     * automation can be controlled even with the window closed.
+     */
+    private void addTrayIcon() {
+        PopupMenu menu = new PopupMenu();
+
+        trayToggleItem = new MenuItem();
+        trayToggleItem.addActionListener(e -> toggleRunning());
+        menu.add(trayToggleItem);
+
+        MenuItem quitItem = new MenuItem("Quit");
+        quitItem.addActionListener(e -> {
+            cleanup();
+            System.exit(0);
+        });
+        menu.add(quitItem);
+
+        trayIcon = new TrayIcon(createTrayIconImage(), "autosqueal", menu);
+        trayIcon.setImageAutoSize(true);
+
+        try {
+            SystemTray.getSystemTray().add(trayIcon);
+        } catch (AWTException ex) {
+            LOGGER.error("Could not add the tray icon", ex);
+            trayIcon = null;
+            trayToggleItem = null;
         }
-
-        // Create a buffered image with transparency
-        BufferedImage bimage = new BufferedImage(img.getWidth(null), img.getHeight(null), BufferedImage.TYPE_INT_ARGB);
-
-        // Draw the image on to the buffered image
-        Graphics2D bGr = bimage.createGraphics();
-        bGr.drawImage(img, 0, 0, null);
-        bGr.dispose();
-
-        // Return the buffered image
-        return bimage;
     }
 
+    /** Draws the little mouse pointer used as tray icon. */
+    private Image createTrayIconImage() {
+        BufferedImage image = new BufferedImage(16, 16, BufferedImage.TYPE_INT_ARGB);
+
+        int[] xPoints = {3, 3, 6, 8, 10, 8, 12};
+        int[] yPoints = {1, 12, 8, 12, 11, 7, 7};
+
+        Graphics2D graphics = image.createGraphics();
+        graphics.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON);
+        graphics.setColor(Color.BLACK);
+        graphics.fillPolygon(xPoints, yPoints, xPoints.length);
+        graphics.setColor(Color.WHITE);
+        graphics.drawPolygon(xPoints, yPoints, xPoints.length);
+        graphics.dispose();
+
+        return image;
+    }
+
+    /** Stops the automation and releases everything the app is holding. */
+    private void cleanup() {
+        LOGGER.info("Shutting down...");
+        stopAutomation();
+
+        if (trayIcon != null) {
+            SystemTray.getSystemTray().remove(trayIcon);
+            trayIcon = null;
+        }
+
+        Main.unregisterJNativeHook();
+    }
+
+    /**
+     * Explains which permissions the app needs and offers to open each pane.
+     * the hook is retried on demand, so the app can start working without a
+     * restart. must be called on the EDT, after the window is visible.
+     */
+    public void showPermissionsHelp() {
+        Object[] options = {"Open Device Control Settings", "Open Screen Recording Settings", "Try Again", "Close"};
+
+        while (true) {
+            int choice = JOptionPane.showOptionDialog(frame,
+                    "autosqueal needs three separate permissions to work:\n\n"
+                            + "1. device control and data access — called \"accessibility\" on older macos\n"
+                            + "   versions — lets the app listen for the ctrl+alt hotkey.\n"
+                            + "   if the pane shows a separate \"events\" switch for autosqueal, turn\n"
+                            + "   that on too: it is what lets the app move the mouse and click.\n\n"
+                            + "2. screen recording — lets the app take the screenshot shown\n"
+                            + "   in the main window.\n\n"
+                            + "open each pane, unlock it, and make sure autosqueal is listed and switched on.\n"
+                            + "if it is already listed, remove it with the minus button and re-add it:\n"
+                            + "every rebuild looks like a different app to the system.\n"
+                            + "when you are done, press \"try again\".",
+                    "permissions needed",
+                    JOptionPane.DEFAULT_OPTION,
+                    JOptionPane.WARNING_MESSAGE,
+                    null,
+                    options,
+                    options[0]);
+
+            if (choice == 0) {
+                openPrivacyPane("Privacy_Accessibility");
+            } else if (choice == 1) {
+                openPrivacyPane("Privacy_ScreenCapture");
+            } else if (choice == 2) {
+                if (Main.registerJNativeHook()) {
+                    LOGGER.info("The native hook was registered on a later attempt!");
+                    return;
+                }
+            } else {
+                // closed or gave up: leave the app running, the window and the
+                // tray icon still work
+                return;
+            }
+        }
+    }
+
+    /** Opens the privacy & security pane for the given anchor. */
+    private void openPrivacyPane(String privacyAnchor) {
+        if (SystemUtil.getHostSystem() != SystemUtil.OperatingSystem.MAC_OS) {
+            return;
+        }
+
+        try {
+            new ProcessBuilder("open",
+                    "x-apple.systempreferences:com.apple.preference.security?" + privacyAnchor)
+                    .start();
+        } catch (IOException ex) {
+            LOGGER.error("Could not open the system settings", ex);
+        }
+    }
+
+    /**
+     * Toggles the automation on or off. Safe to call from any thread: the actual
+     * work is always marshalled to the EDT, since it touches Swing components.
+     */
     public void toggleRunning() {
-
-        String label;
-
-        if (cursorMover == null) {
-            timerRunner = new Timer();
-            CursorMoveListener cursorMoveListener = new CursorMoveListener();
-            timerRunner.schedule(cursorMoveListener, 0L, 1000L);
-
-            cursorMover = new CursorMover();
-            timerRunner.schedule(cursorMover, 1000L, RunnerUtil.SECONDS_BETWEEN_MOVES * 1000L);
-
-            label = "Stop [" +
-                    NativeKeyEvent.getKeyText(NativeKeyEvent.VC_CONTROL) +
-                    "][" +
-                    NativeKeyEvent.getKeyText(NativeKeyEvent.VC_ALT) +
-                    "]";
-        }
-        else {
-            timerRunner.cancel();
-
-            cursorMover = null;
-
-            label = "Start [" +
-                    NativeKeyEvent.getKeyText(NativeKeyEvent.VC_CONTROL) +
-                    "][" +
-                    NativeKeyEvent.getKeyText(NativeKeyEvent.VC_ALT) +
-                    "]";
-        }
-
-        toggleButton.setLabel(label);
-
+        SwingUtilities.invokeLater(() -> {
+            if (cursorMover == null) {
+                startAutomation();
+            } else {
+                stopAutomation();
+            }
+            updateToggleLabel();
+        });
     }
 
-}
+    private void startAutomation() {
+        LOGGER.info("Starting automation");
+
+        // periodic work (polling and movement cadence) on a classic scheduler,
+        // so that it can be scheduled with fixed delays
+        periodicScheduler = Executors.newScheduledThreadPool(2, runnable -> {
+            Thread thread = new Thread(runnable, "autosqueal-scheduler");
+            thread.setDaemon(true);
+            return thread;
+        });
+
+        // movements and clicks run on virtual threads: they mostly sleep,
+        // and blocking them costs nothing
+        movementExecutor = Executors.newThreadPerTaskExecutor(
+                Thread.ofVirtual().name("autosqueal-movement-").factory());
+
+        // away-detection: polls the cursor position and ignores the movements
+        // the app performs itself, as reported by the robot mouse tracker.
+        // the automation only moves the mouse when the user is away.
+        RobotMouseTracker robotTracker = new RobotMouseTracker();
+        CursorMoveListener cursorMoveListener = new CursorMoveListener(robotTracker);
+        periodicScheduler.scheduleWithFixedDelay(cursorMoveListener, 0L, AWAY_POLL_INTERVAL_SECONDS, TimeUnit.SECONDS);
+
+        cursorMover = new CursorMover(movementExecutor, robotTracker, cursorMoveListener::isUserAway);
+        periodicScheduler.scheduleWithFixedDelay(cursorMover,
+                AUTOMATION_START_DELAY_SECONDS,
+                RunnerUtil.SECONDS_BETWEEN_MOVES,
+                TimeUnit.SECONDS);
+    }
+
+    private void stopAutomation() {
+        LOGGER.info("Stopping automation");
+
+        if (periodicScheduler != null) {
+            periodicScheduler.shutdownNow();
+            periodicScheduler = null;
+        }
+
+        if (movementExecutor != null) {
+            // interrupts the in-flight movement threads, too
+            movementExecutor.shutdownNow();
+            movementExecutor = null;
+        }
+
+        cursorMover = null;
+    }
+
+    private void updateToggleLabel() {
+        if (toggleButton == null) {
+            // the window is not initialized yet
+            return;
+        }
+
+        String hotkey = "[" + NativeKeyEvent.getKeyText(NativeKeyEvent.VC_CONTROL) + "]"
+                + "[" + NativeKeyEvent.getKeyText(NativeKeyEvent.VC_ALT) + "]";
+
+        String label = (cursorMover == null ? "Start " : "Stop ") + hotkey;
+
+        toggleButton.setText(label);
+        if (trayToggleItem != null) {
+            trayToggleItem.setLabel(label);
+        }
+    }
+
+}

src/main/java/wtf/beatrice/autosqueal/util/SystemUtil.java

@@ -6,14 +6,18 @@ public class SystemUtil
 {
 
     public static OperatingSystem getHostSystem() {
-        String osName = System.getProperty("os.name").toLowerCase(Locale.ENGLISH);
-        if (osName.contains("win")) {
+        return fromOsName(System.getProperty("os.name"));
+    }
+
+    public static OperatingSystem fromOsName(String osName) {
+        String normalizedOsName = osName.toLowerCase(Locale.ENGLISH);
+        if (normalizedOsName.contains("win")) {
             return OperatingSystem.WINDOWS;
-        } else if (osName.contains("nix") ||
-                osName.contains("nux") ||
-                osName.contains("aix")) {
+        } else if (normalizedOsName.contains("nix") ||
+                normalizedOsName.contains("nux") ||
+                normalizedOsName.contains("aix")) {
             return OperatingSystem.LINUX;
-        } else if (osName.contains("mac")) {
+        } else if (normalizedOsName.contains("mac")) {
             return OperatingSystem.MAC_OS;
         } else {
             return OperatingSystem.UNKNOWN;

src/main/resources/log4j2.xml

@@ -8,7 +8,6 @@
     <Loggers>
         <Root level="debug">
             <AppenderRef ref="ConsoleAppender" />
-            <AppenderRef ref="FileAppender"/>
         </Root>
     </Loggers>
 </Configuration>

src/test/java/wtf/beatrice/autosqueal/controls/RobotMouseTrackerTest.java

@@ -0,0 +1,31 @@
+package wtf.beatrice.autosqueal.controls;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class RobotMouseTrackerTest
+{
+    @Test
+    void startsIdle() {
+        RobotMouseTracker tracker = new RobotMouseTracker();
+
+        assertFalse(tracker.isMoving());
+        assertFalse(tracker.isLastPosition(10, 20));
+    }
+
+    @Test
+    void tracksOngoingMovement() {
+        RobotMouseTracker tracker = new RobotMouseTracker();
+
+        tracker.moveStarted();
+        assertTrue(tracker.isMoving());
+
+        tracker.moveEnded(15, 25);
+        assertFalse(tracker.isMoving());
+        assertTrue(tracker.isLastPosition(15, 25));
+        assertFalse(tracker.isLastPosition(15, 26));
+        assertFalse(tracker.isLastPosition(25, 15));
+    }
+}

src/test/java/wtf/beatrice/autosqueal/controls/SingleStepMovementTaskTest.java

@@ -0,0 +1,117 @@
+package wtf.beatrice.autosqueal.controls;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.fail;
+
+class SingleStepMovementTaskTest
+{
+    private static final int MAX_TICKS = 20_000;
+    private static final float DELTA = 0.0f;
+
+    @Test
+    void noStepWhenAlreadyAtDestination() {
+        assertEquals(0.0f, SingleStepMovementTask.computeStepX(0, 0), DELTA);
+        assertEquals(0.0f, SingleStepMovementTask.computeStepY(0, 0), DELTA);
+    }
+
+    @Test
+    void axisAlignedMovementsProduceNoInfiniteSteps() {
+        // moving only horizontally: the y step must be 0, not Infinity or NaN
+        assertEquals(1.0f, SingleStepMovementTask.computeStepX(100, 0), DELTA);
+        assertEquals(0.0f, SingleStepMovementTask.computeStepY(100, 0), DELTA);
+
+        // moving only vertically: the x step must be 0, not Infinity or NaN
+        assertEquals(0.0f, SingleStepMovementTask.computeStepX(0, 100), DELTA);
+        assertEquals(1.0f, SingleStepMovementTask.computeStepY(0, 100), DELTA);
+    }
+
+    @Test
+    void diagonalMovementsMoveBothAxes() {
+        assertEquals(1.0f, SingleStepMovementTask.computeStepX(100, 100), DELTA);
+        assertEquals(1.0f, SingleStepMovementTask.computeStepY(100, 100), DELTA);
+
+        assertEquals(0.5f, SingleStepMovementTask.computeStepX(50, 100), DELTA);
+        assertEquals(1.0f, SingleStepMovementTask.computeStepY(50, 100), DELTA);
+
+        assertEquals(1.0f, SingleStepMovementTask.computeStepX(100, 50), DELTA);
+        assertEquals(0.5f, SingleStepMovementTask.computeStepY(100, 50), DELTA);
+    }
+
+    @Test
+    void stepsAreNeverInfiniteOrNaN() {
+        for (int lengthX = 0; lengthX <= 400; lengthX += 7) {
+            for (int lengthY = 0; lengthY <= 400; lengthY += 7) {
+                float stepX = SingleStepMovementTask.computeStepX(lengthX, lengthY);
+                float stepY = SingleStepMovementTask.computeStepY(lengthX, lengthY);
+
+                assertFalse(Float.isInfinite(stepX), "infinite stepX for lengths [" + lengthX + ", " + lengthY + "]");
+                assertFalse(Float.isNaN(stepX), "NaN stepX for lengths [" + lengthX + ", " + lengthY + "]");
+                assertFalse(Float.isInfinite(stepY), "infinite stepY for lengths [" + lengthX + ", " + lengthY + "]");
+                assertFalse(Float.isNaN(stepY), "NaN stepY for lengths [" + lengthX + ", " + lengthY + "]");
+            }
+        }
+    }
+
+    @Test
+    void advanceMovesTowardTheDestination() {
+        assertEquals(5.0f, SingleStepMovementTask.advance(5.0f, 5.0f, 1.0f), DELTA); // already there
+        assertEquals(9.0f, SingleStepMovementTask.advance(10.0f, 5.0f, 1.0f), DELTA); // decreasing
+        assertEquals(6.0f, SingleStepMovementTask.advance(5.0f, 10.0f, 1.0f), DELTA); // increasing
+    }
+
+    @Test
+    void adjustedStepUsesExactRemainderWhenClose() {
+        assertEquals(0.4f, SingleStepMovementTask.adjustedStep(10.0f, 10.4f, 1.0f), 0.00001f);
+        assertEquals(0.4f, SingleStepMovementTask.adjustedStep(10.8f, 10.4f, 1.0f), 0.00001f);
+        assertEquals(1.0f, SingleStepMovementTask.adjustedStep(10.0f, 20.0f, 1.0f), DELTA);
+    }
+
+    @Test
+    void movementConvergesToDestination() {
+        record MovementCase(float startX, float startY, int destX, int destY) {}
+
+        MovementCase[] cases = {
+                new MovementCase(100, 100, 500, 500),   // plain diagonal
+                new MovementCase(500, 500, 100, 100),   // going up-left
+                new MovementCase(100, 100, 500, 100),   // horizontal (used to break: infinite step)
+                new MovementCase(500, 100, 100, 100),   // horizontal, other direction
+                new MovementCase(100, 100, 100, 500),   // vertical (used to break: infinite step)
+                new MovementCase(100, 500, 100, 100),   // vertical, other direction
+                new MovementCase(105, 105, 105, 105),   // already at destination
+                new MovementCase(0, 0, 2000, 1000),     // steep diagonal
+                new MovementCase(2000, 1000, 0, 0),     // same, backwards
+                new MovementCase(37, 173, 2311, 997),   // random-ish, both directions mixed
+        };
+
+        for (MovementCase move : cases) {
+            float x = move.startX();
+            float y = move.startY();
+
+            int lengthX = Math.round(Math.abs(x - move.destX()));
+            int lengthY = Math.round(Math.abs(y - move.destY()));
+            float stepX = SingleStepMovementTask.computeStepX(lengthX, lengthY);
+            float stepY = SingleStepMovementTask.computeStepY(lengthX, lengthY);
+
+            boolean converged = false;
+            for (int tick = 0; tick < MAX_TICKS; tick++) {
+                if (Math.round(x) == move.destX() && Math.round(y) == move.destY()) {
+                    converged = true;
+                    break;
+                }
+
+                stepX = SingleStepMovementTask.adjustedStep(x, move.destX(), stepX);
+                stepY = SingleStepMovementTask.adjustedStep(y, move.destY(), stepY);
+                x = SingleStepMovementTask.advance(x, move.destX(), stepX);
+                y = SingleStepMovementTask.advance(y, move.destY(), stepY);
+            }
+
+            if (!converged) {
+                fail("movement did not converge: stuck at [" + Math.round(x) + ", " + Math.round(y)
+                        + "] while heading to [" + move.destX() + ", " + move.destY() + "]");
+            }
+        }
+    }
+}

src/test/java/wtf/beatrice/autosqueal/listener/CursorMoveListenerTest.java

@@ -0,0 +1,167 @@
+package wtf.beatrice.autosqueal.listener;
+
+import org.junit.jupiter.api.Test;
+import wtf.beatrice.autosqueal.controls.RobotMouseTracker;
+
+import java.awt.*;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Queue;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class CursorMoveListenerTest
+{
+    private static final int LOOPS_BEFORE_AWAY = 30;
+
+    private final RobotMouseTracker robotTracker = new RobotMouseTracker();
+
+    /** Builds a listener that reads scripted cursor positions, one per poll. */
+    private CursorMoveListener scriptedListener(Point... positions) {
+        Queue<Point> positionQueue = new ArrayDeque<>(java.util.List.of(positions));
+        return new CursorMoveListener(robotTracker, positionQueue::remove);
+    }
+
+    private static Point at(int x, int y) {
+        return new Point(x, y);
+    }
+
+    @Test
+    void userIsAwayAfterThirtyStillSeconds() {
+        Point[] still = new Point[LOOPS_BEFORE_AWAY + 2];
+        for (int i = 0; i < still.length; i++) {
+            still[i] = at(100, 100);
+        }
+        CursorMoveListener listener = scriptedListener(still);
+
+        // the first poll seeds the baseline and does not count
+        for (int i = 0; i < LOOPS_BEFORE_AWAY; i++) {
+            listener.run();
+            assertFalse(listener.isUserAway());
+        }
+
+        listener.run();
+        assertTrue(listener.isUserAway());
+    }
+
+    @Test
+    void firstPollDoesNotCountAsMovement() {
+        // the very first position read must seed the baseline: starting anywhere
+        // else would have counted as a user movement and reset the away timer
+        CursorMoveListener listener = scriptedListener(at(500, 300), at(500, 300));
+
+        listener.run();
+        listener.run();
+
+        assertFalse(listener.isUserAway());
+        // still at (500, 300), so the baseline was seeded correctly
+    }
+
+    @Test
+    void userMovementResetsTheAwayTimer() {
+        List<Point> positions = new ArrayList<>();
+        positions.add(at(100, 100));                              // baseline
+        for (int i = 0; i < 5; i++) positions.add(at(100, 100)); // 5 still polls
+        positions.add(at(140, 100));                              // the user moves the mouse
+        for (int i = 0; i < LOOPS_BEFORE_AWAY; i++) positions.add(at(140, 100)); // then it stays put
+
+        CursorMoveListener listener = scriptedListener(positions.toArray(Point[]::new));
+
+        listener.run(); // seed the baseline
+        for (int i = 0; i < 5; i++) listener.run(); // loops = 5
+        assertFalse(listener.isUserAway());
+
+        listener.run(); // the user moved: the away timer resets
+        assertFalse(listener.isUserAway());
+
+        // ...and it still takes 30 more still polls to be away again
+        for (int i = 0; i < LOOPS_BEFORE_AWAY - 1; i++) listener.run(); // loops = 29
+        assertFalse(listener.isUserAway());
+
+        listener.run(); // loops = 30
+        assertTrue(listener.isUserAway());
+    }
+
+    @Test
+    void appMovementsDoNotKeepTheUserPresent() {
+        // this is the regression the away detection was disconnected for: the
+        // app moves the mouse every few seconds, and before the fix those
+        // movements were indistinguishable from the user's, so the app would
+        // always think the user was present
+
+        // every poll finds the cursor where the app last left it
+        List<Point> positions = new ArrayList<>();
+        positions.add(at(100, 100)); // baseline
+        for (int i = 1; i <= 40; i++) positions.add(at(100 + i, 100));
+
+        CursorMoveListener listener = scriptedListener(positions.toArray(Point[]::new));
+
+        listener.run(); // seed the baseline
+
+        for (int i = 1; i <= 40; i++) {
+            // the app just finished a movement, leaving the cursor exactly
+            // where this poll will find it
+            robotTracker.moveEnded(100 + i, 100);
+            listener.run();
+        }
+
+        // every position change was the app's own doing: the user is away
+        assertTrue(listener.isUserAway());
+    }
+
+    @Test
+    void ongoingAppMovementsDoNotKeepTheUserPresent() {
+        // same as above, but the polls happen while the app is mid-movement,
+        // with the cursor transiently at intermediate positions
+        Point[] positions = new Point[41];
+        positions[0] = at(100, 100);
+        for (int i = 1; i < positions.length; i++) {
+            positions[i] = at(100 + (i / 2), 100);
+        }
+        CursorMoveListener listener = scriptedListener(positions);
+
+        robotTracker.moveStarted();
+        for (int i = 1; i < positions.length; i++) {
+            listener.run();
+        }
+
+        assertTrue(listener.isUserAway());
+    }
+
+    @Test
+    void userComingBackIsDetectedWhileTheAppIsWiggling() {
+        // the app keeps wiggling while the user is away; when the user comes
+        // back and moves the mouse, the away state must end
+
+        // polls: baseline, 30 still polls, two app wiggles, then the user's move
+        Point[] positions = new Point[LOOPS_BEFORE_AWAY + 4];
+        for (int i = 0; i <= LOOPS_BEFORE_AWAY; i++) {
+            positions[i] = at(100, 100);
+        }
+        positions[LOOPS_BEFORE_AWAY + 1] = at(150, 100);
+        positions[LOOPS_BEFORE_AWAY + 2] = at(200, 100);
+        positions[LOOPS_BEFORE_AWAY + 3] = at(333, 100);
+        CursorMoveListener listener = scriptedListener(positions);
+
+        // baseline + 30 still polls: the user goes away
+        for (int i = 0; i <= LOOPS_BEFORE_AWAY; i++) {
+            listener.run();
+        }
+        assertTrue(listener.isUserAway());
+
+        // the app wiggles: each movement is discounted, the user stays "away"
+        robotTracker.moveEnded(150, 100);
+        listener.run();
+        assertTrue(listener.isUserAway());
+
+        robotTracker.moveEnded(200, 100);
+        listener.run();
+        assertTrue(listener.isUserAway());
+
+        // the user comes back and grabs the mouse
+        listener.run();
+        assertFalse(listener.isUserAway());
+    }
+}

src/test/java/wtf/beatrice/autosqueal/util/SystemUtilTest.java

@@ -0,0 +1,34 @@
+package wtf.beatrice.autosqueal.util;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class SystemUtilTest
+{
+    @Test
+    void detectsWindows() {
+        assertEquals(SystemUtil.OperatingSystem.WINDOWS, SystemUtil.fromOsName("Windows 11"));
+    }
+
+    @Test
+    void detectsLinux() {
+        assertEquals(SystemUtil.OperatingSystem.LINUX, SystemUtil.fromOsName("Linux"));
+        assertEquals(SystemUtil.OperatingSystem.LINUX, SystemUtil.fromOsName("GNU/Linux"));
+    }
+
+    @Test
+    void detectsMacOS() {
+        assertEquals(SystemUtil.OperatingSystem.MAC_OS, SystemUtil.fromOsName("Mac OS X"));
+    }
+
+    @Test
+    void unknownForOtherSystems() {
+        assertEquals(SystemUtil.OperatingSystem.UNKNOWN, SystemUtil.fromOsName("SunOS"));
+    }
+
+    @Test
+    void hostSystemMatchesOsName() {
+        assertEquals(SystemUtil.fromOsName(System.getProperty("os.name")), SystemUtil.getHostSystem());
+    }
+}