Add pluggable movement strategies (v1.3.0)

Turn the hardcoded straight-line sweep into a strategy system behind three
seams so new patterns are easy to add and, for the first time, testable
without nut.js or a real screen:

- src/device.ts:     injectable Device seam over nut.js (autoDelayMs lives
                     here now); the only module that touches the native lib.
- src/strategies.ts: pure per-pattern path generators + registry + lenient
                     name resolution. Ships line, diagonal, jitter, walk,
                     arc, figureEight.
- src/executor.ts:   single executePath driver owning bounds policy
                     (abort/clamp/reflect), pacing, interrupt detection, and
                     restore-on-clean.

keeper.ts's simulateActivity now selects a strategy and delegates to the
executor; the default `line` pattern is byte-for-byte the previous behavior.

New config surface, layered CLI > file > default with strict validation:
- -p/--pattern <name>   movement strategy (names matched case/-/_-insensitive)
- -s/--step-size <px>   pixels per step; stepCount is now a step *count*

Robustness for the new edge-seeking patterns: interrupt detection compares
against the last commanded (rounded) point with a 2px tolerance, and
clamp/reflect stay a couple pixels off the screen edge, so sub-pixel cursor
placement on scaled/multi-monitor displays isn't misread as user activity.
jitter's radius scales with sweep length so it moves at the default stepSize.

Tests: new suites for strategies, the executor (all bounds policies,
rounding, interrupt, tolerance, pacing), and the keeper loop; config and
configFile suites extended for pattern/stepSize. editor.test.ts moved to
tests/ for consistency. 64 pass.

src/executor.ts

@@ -0,0 +1,192 @@
+/**
+ * executor.ts
+ * -----------
+ * The single execution driver shared by every movement strategy.
+ *
+ * A strategy (`strategies.ts`) says *where* to go; this module owns
+ * *everything else* about carrying a sweep out against a `Device`:
+ *
+ *   - round each ideal target to whole pixels,
+ *   - keep it on-screen per the strategy's `BoundsPolicy`,
+ *   - command the cursor and pace it with `stepDelay`,
+ *   - detect real-user interruption after each step,
+ *   - restore the cursor to the origin on a clean run.
+ *
+ * Writing this once means new patterns inherit correct real-user-wins,
+ * bounds, and restore semantics for free. It's pure with respect to I/O —
+ * all side effects go through the injected `Device`, so it's unit-testable
+ * with a fake.
+ *
+ * Interrupt detection compares the re-read cursor against the *last
+ * commanded (rounded) point*, never the strategy's ideal (possibly
+ * fractional) target. That's what lets curved/stochastic patterns work
+ * without every rounded step being misread as "the user moved the mouse".
+ */
+
+import type { Device, Point } from "./device.ts";
+import type { BoundsPolicy, MoveContext, MovementStrategy } from "./strategies.ts";
+
+/**
+ * Minimal log surface used by the executor and the keeper loop.
+ *
+ *  - `info(msg)`  prints unconditionally (startup banner, fatal notes).
+ *  - `event(msg)` prints only under `--verbose` / `verbose: true`.
+ */
+export interface Logger {
+    info(msg: string): void;
+    event(msg: string): void;
+}
+
+/**
+ * How a sweep ended:
+ *  - `completed`   — full path ran and the cursor was restored to start.
+ *  - `interrupted` — real user activity detected mid-sweep; aborted without
+ *                    snapping back.
+ *  - `aborted`     — an `abort`-policy target went out of bounds.
+ */
+export type SweepOutcome = "completed" | "interrupted" | "aborted";
+
+/**
+ * Slack, in pixels, allowed between the coordinate we commanded and the one
+ * we read back before calling it real-user activity. Absorbs the sub-pixel
+ * placement error the OS can introduce on scaled or multi-monitor setups; a
+ * genuine user movement is far larger than this.
+ */
+const READBACK_TOLERANCE: number = 2;
+
+/**
+ * Pixels to inset the `clamp` / `reflect` travel range from each screen edge.
+ * Keeps edge-seeking patterns off the literal first/last pixel, where DPI
+ * scaling and multi-monitor boundaries most often make the OS place the
+ * cursor a hair off what we commanded (which the readback check would then
+ * misread as the user). `abort` (used by `line`) is deliberately left on the
+ * full `[0, max - 1]` range, so its behavior is unchanged.
+ */
+const EDGE_MARGIN: number = 2;
+
+/**
+ * The inclusive `[lo, hi]` integer range an axis of length `max` may travel
+ * under the `clamp` / `reflect` policies: `[0, max - 1]` inset by
+ * `EDGE_MARGIN` on each side. Screens too small to inset fall back to the
+ * full range so the math never inverts.
+ */
+function travelRange(max: number): { lo: number; hi: number } {
+    const hiEdge: number = max - 1;
+    if (hiEdge - 2 * EDGE_MARGIN < 1) return { lo: 0, hi: Math.max(0, hiEdge) };
+    return { lo: EDGE_MARGIN, hi: hiEdge - EDGE_MARGIN };
+}
+
+/** Round to whole pixels and clamp into the inset travel range for `max`. */
+function clampInt(v: number, max: number): number {
+    const { lo, hi } = travelRange(max);
+    const r: number = Math.round(v);
+    if (r < lo) return lo;
+    if (r > hi) return hi;
+    return r;
+}
+
+/**
+ * Mirror `v` into the inset travel range for `max` as a triangle wave, so
+ * values past an edge bounce back inside instead of clamping flat against it.
+ */
+function reflectInt(v: number, max: number): number {
+    const { lo, hi } = travelRange(max);
+    const span: number = hi - lo;
+    if (span <= 0) return lo;
+    const period: number = 2 * span;
+    const m: number = (((Math.round(v) - lo) % period) + period) % period;
+    return lo + (m <= span ? m : period - m);
+}
+
+/**
+ * Resolve a strategy's ideal target to an on-screen integer pixel under the
+ * given policy. Returns `null` when policy is `abort` and the (rounded)
+ * target lies outside the screen — the signal to stop the sweep.
+ */
+function resolveTarget(
+    policy: BoundsPolicy,
+    p: Point,
+    width: number,
+    height: number,
+): Point | null {
+    if (policy === "reflect") {
+        return { x: reflectInt(p.x, width), y: reflectInt(p.y, height) };
+    }
+    if (policy === "clamp") {
+        return { x: clampInt(p.x, width), y: clampInt(p.y, height) };
+    }
+    // abort: round, then reject anything off-screen.
+    const x: number = Math.round(p.x);
+    const y: number = Math.round(p.y);
+    if (x < 0 || x >= width || y < 0 || y >= height) return null;
+    return { x, y };
+}
+
+/**
+ * Format the current local time as `HH:MM:SS` for log lines.
+ */
+function timestamp(): string {
+    const d: Date = new Date();
+    const pad = (n: number): string => String(n).padStart(2, "0");
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+/**
+ * Run one sweep: drive `strategy.path(ctx)` to completion (or early exit)
+ * against `device`.
+ *
+ * Contract, per step:
+ *   1. Resolve the ideal target to an on-screen integer (bounds policy).
+ *      An `abort`-policy out-of-bounds target ends the sweep (`aborted`).
+ *   2. Command the cursor there and sleep `stepDelay` — also the user's
+ *      interrupt window.
+ *   3. Re-read the cursor. If it isn't at the point we just commanded, the
+ *      user moved it: return `interrupted` without restoring.
+ *
+ * On a clean run the cursor is restored to `ctx.start` so the next
+ * idle-check sees no net movement, and `completed` is returned.
+ */
+export async function executePath(
+    strategy: MovementStrategy,
+    ctx: MoveContext,
+    device: Device,
+    log: Logger,
+): Promise<SweepOutcome> {
+    const { start, width, height, config } = ctx;
+
+    log.event(`Simulating activity (${strategy.name}) at ${timestamp()}...`);
+
+    for (const target of strategy.path(ctx)) {
+        const point: Point | null = resolveTarget(strategy.bounds, target, width, height);
+        if (point === null) {
+            log.event(`Out of bounds at ${timestamp()}; aborting simulation.`);
+            return "aborted";
+        }
+
+        await device.setPosition(point);
+        await device.sleep(config.stepDelay);
+
+        const current: Point = await device.getPosition();
+        if (
+            Math.abs(current.x - point.x) > READBACK_TOLERANCE ||
+            Math.abs(current.y - point.y) > READBACK_TOLERANCE
+        ) {
+            // Cursor isn't where we last put it -> real user activity. Abort
+            // without snapping back, so we don't yank it from under the user.
+            //
+            // The comparison allows a small tolerance rather than demanding an
+            // exact match: on scaled (fractional-DPI) or multi-monitor setups
+            // the OS can place the cursor a pixel off the coordinate we
+            // commanded, and the edge-seeking patterns (clamp/reflect/arc)
+            // reach exactly the coordinates where that's most likely. A real
+            // user moves far more than a couple of pixels, so this doesn't
+            // meaningfully weaken real-user-wins.
+            log.event(`User activity detected at ${timestamp()}; aborting simulation.`);
+            return "interrupted";
+        }
+    }
+
+    await device.setPosition({ x: Math.round(start.x), y: Math.round(start.y) });
+    log.event("Mouse moved.");
+    return "completed";
+}