stelo 1.0.1

package/dist/mouse.d.ts

@@ -0,0 +1,290 @@
+import type { MouseButton, Point, ScrollDirection, SmoothMoveOptions, HumanizedMoveOptions, DragOptions } from './types';
+/** Handle returned by async movement operations for cancellation. */
+export interface MovementHandle {
+    /** Promise that resolves when the movement completes or is cancelled. */
+    promise: Promise<Point>;
+    /** Cancel the movement. The cursor stays at its current position. */
+    cancel(): void;
+}
+/**
+ * Mouse control interface.
+ *
+ * @example
+ * ```typescript
+ * import { mouse } from 'stelo';
+ *
+ * // Instant move
+ * mouse.move(100, 200);
+ *
+ * // Smooth bezier movement
+ * mouse.moveSmoothly(500, 400, { duration: 1000, curve: 'bezier' });
+ *
+ * // Human-like movement
+ * mouse.moveHumanized(800, 600);
+ *
+ * // Click, double-click, right-click
+ * mouse.click();
+ * mouse.doubleClick();
+ * mouse.click('right');
+ *
+ * // Drag
+ * mouse.drag(100, 100, 500, 400);
+ *
+ * // Scroll
+ * mouse.scroll(3, 'up');
+ * ```
+ */
+export declare const mouse: {
+    /**
+     * Move cursor instantly to absolute screen coordinates.
+     */
+    move(x: number, y: number): void;
+    /**
+     * Get current cursor position.
+     */
+    getPosition(): Point;
+    /**
+     * Move cursor smoothly to target with configurable curve and duration.
+     */
+    moveSmoothly(x: number, y: number, options?: SmoothMoveOptions): void;
+    /**
+     * Move cursor with humanized, natural-feeling motion.
+     * Includes micro-jitter, variable speed, and optional overshoot.
+     */
+    moveHumanized(x: number, y: number, options?: HumanizedMoveOptions): void;
+    /**
+     * Click a mouse button at the current position.
+     * @param button - 'left' (default), 'right', or 'middle'
+     */
+    click(button?: MouseButton): void;
+    /**
+     * Double-click a mouse button.
+     */
+    doubleClick(button?: MouseButton): void;
+    /**
+     * Triple-click (select line/paragraph).
+     */
+    tripleClick(button?: MouseButton): void;
+    /**
+     * Press (hold down) a mouse button without releasing.
+     */
+    down(button?: MouseButton): void;
+    /**
+     * Release a mouse button.
+     */
+    up(button?: MouseButton): void;
+    /**
+     * Scroll the mouse wheel.
+     * @param amount - Number of scroll increments
+     * @param direction - 'up' (default), 'down', 'left', 'right'
+     */
+    scroll(amount?: number, direction?: ScrollDirection): void;
+    /**
+     * Scroll the mouse wheel smoothly over time.
+     * @param amount - Number of scroll increments
+     * @param direction - 'up' (default), 'down', 'left', 'right'
+     * @param duration - Duration of the scroll in ms
+     */
+    scrollSmooth(amount?: number, direction?: ScrollDirection, duration?: number): void;
+    /**
+     * Drag from one point to another.
+     */
+    drag(fromX: number, fromY: number, toX: number, toY: number, options?: DragOptions): void;
+    /**
+     * Click at a specific position.
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     * @param button - Mouse button (default: 'left')
+     * @param restorePosition  If true, returns cursor to original position after clicking
+     */
+    clickAt(x: number, y: number, button?: MouseButton, restorePosition?: boolean): void;
+    /**
+     * Move to a position and click in one call.
+     */
+    moveAndClick(x: number, y: number, button?: MouseButton): void;
+    /**
+     * Move cursor smoothly to target — **non-blocking**.
+     *
+     * Unlike `moveSmoothly()` (which blocks the thread), this method yields
+     * control back to the event loop between each step. The cursor moves
+     * visually on-screen and other code (screen captures, AI inference, etc.)
+     * can run in parallel.
+     *
+     * @returns A `MovementHandle` with `.promise` and `.cancel()`.
+     *
+     * @example
+     * ```typescript
+     * // Simple await
+     * await mouse.moveSmoothAsync(500, 400, { duration: 600 });
+     *
+     * // Cancel mid-flight
+     * const handle = mouse.moveSmoothAsync(500, 400);
+     * setTimeout(() => handle.cancel(), 200);
+     * await handle.promise;
+     *
+     * // Run movement + screen monitoring in parallel
+     * const [_, frame] = await Promise.all([
+     *   mouse.moveSmoothAsync(500, 400).promise,
+     *   captureScreenDuringMovement(),
+     * ]);
+     * ```
+     */
+    moveSmoothAsync(x: number, y: number, options?: SmoothMoveOptions): MovementHandle;
+    /**
+     * Move cursor with humanized motion — **non-blocking**.
+     *
+     * Same as `moveHumanized()` but non-blocking. The cursor visually traces
+     * a natural-looking path with jitter and variable speed, while the event
+     * loop stays free for other operations.
+     *
+     * @returns A `MovementHandle` with `.promise` and `.cancel()`.
+     */
+    moveHumanizedAsync(x: number, y: number, options?: HumanizedMoveOptions): MovementHandle;
+    /**
+     * Move the cursor along an arbitrary path of points — **non-blocking**.
+     *
+     * Pass any array of `{ x, y }` waypoints. The cursor follows the path
+     * with the given delay between each point. Ideal for replaying recorded
+     * gestures, following geometry, or executing complex paths from AI models.
+     *
+     * @returns A `MovementHandle` with `.promise` and `.cancel()`.
+     *
+     * @example
+     * ```typescript
+     * // Trace a rectangle
+     * await mouse.moveAlongPath([
+     *   { x: 100, y: 100 },
+     *   { x: 500, y: 100 },
+     *   { x: 500, y: 400 },
+     *   { x: 100, y: 400 },
+     *   { x: 100, y: 100 },
+     * ], { stepDelayMs: 5 }).promise;
+     * ```
+     */
+    moveAlongPath(path: Point[], options?: {
+        stepDelayMs?: number;
+    }): MovementHandle;
+    /**
+     * Move to target position and click — **non-blocking smooth movement**.
+     *
+     * Smoothly moves to the target, then clicks. Returns after both complete.
+     *
+     * @example
+     * ```typescript
+     * await mouse.moveAndClickAsync(500, 300, { duration: 400 });
+     * ```
+     */
+    moveAndClickAsync(x: number, y: number, options?: SmoothMoveOptions & {
+        button?: MouseButton;
+    }): Promise<void>;
+    /**
+     * Drag from current position to target — **non-blocking smooth movement**.
+     *
+     * The cursor visibly moves to the target while holding the mouse button.
+     *
+     * @example
+     * ```typescript
+     * mouse.move(100, 100);
+     * await mouse.dragAsync(500, 400, { duration: 800 });
+     * ```
+     */
+    dragAsync(toX: number, toY: number, options?: {
+        button?: MouseButton;
+        duration?: number;
+    }): Promise<void>;
+    /**
+     * Get current X coordinate.
+     */
+    readonly x: number;
+    /**
+     * Get current Y coordinate.
+     */
+    readonly y: number;
+    /**
+     * Move the cursor smoothly through a sequence of waypoints.
+     *
+     * @example
+     * ```typescript
+     * // Visit three points with smooth interpolation
+     * mouse.moveThroughPoints([[100,200], [400,300], [600,100]], 1000);
+     * ```
+     */
+    moveThroughPoints(points: [number, number][], durationMs: number, options?: {
+        curve?: string;
+        stepsPerSecond?: number;
+    }): void;
+    /**
+     * Trace a circular gesture around a center point.
+     *
+     * @example
+     * ```typescript
+     * mouse.gestureCircle(500, 400, 100, 1000); // 100px radius circle in 1s
+     * ```
+     */
+    gestureCircle(centerX: number, centerY: number, radius: number, durationMs: number, options?: {
+        clockwise?: boolean;
+        stepsPerSecond?: number;
+    }): void;
+    /**
+     * Fast swipe gesture — flick-like motion between two points.
+     * Optionally holds a mouse button during the swipe (for drag-swipes).
+     *
+     * @example
+     * ```typescript
+     * mouse.gestureSwipe(100, 500, 100, 100, { duration: 150 }); // swipe up
+     * ```
+     */
+    gestureSwipe(fromX: number, fromY: number, toX: number, toY: number, options?: {
+        duration?: number;
+        holdButton?: MouseButton;
+    }): void;
+    /**
+     * Drag along an arbitrary path while holding a mouse button.
+     * Perfect for drawing, resizing, or complex drag operations.
+     *
+     * @example
+     * ```typescript
+     * mouse.gestureDragPath([[100,100], [200,150], [300,100], [400,200]], 1000);
+     * ```
+     */
+    gestureDragPath(points: [number, number][], durationMs: number, options?: {
+        button?: MouseButton;
+        stepsPerSecond?: number;
+    }): void;
+    /**
+     * Spiral inward or outward from a center point.
+     *
+     * @example
+     * ```typescript
+     * // Spiral outward from center, 0→200px radius, 3 turns, 2 seconds
+     * mouse.gestureSpiral(500, 400, 0, 200, 3, 2000);
+     * ```
+     */
+    gestureSpiral(centerX: number, centerY: number, startRadius: number, endRadius: number, turns: number, durationMs: number, options?: {
+        stepsPerSecond?: number;
+    }): void;
+    /**
+     * Zigzag motion — oscillates perpendicular to the travel direction.
+     *
+     * @example
+     * ```typescript
+     * // Zigzag from left to right with 30px amplitude, 5 waves
+     * mouse.gestureZigzag(100, 300, 800, 300, 30, 5, 1000);
+     * ```
+     */
+    gestureZigzag(fromX: number, fromY: number, toX: number, toY: number, amplitude: number, waves: number, durationMs: number, options?: {
+        stepsPerSecond?: number;
+    }): void;
+    /**
+     * Trace a rectangular path — clockwise from top-left corner.
+     *
+     * @example
+     * ```typescript
+     * mouse.gestureRectangle(100, 100, 400, 300, 2000);
+     * ```
+     */
+    gestureRectangle(x: number, y: number, width: number, height: number, durationMs: number, options?: {
+        curve?: string;
+    }): void;
+};
+//# sourceMappingURL=mouse.d.ts.map

package/dist/mouse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mouse.d.ts","sourceRoot":"","sources":["../ts/mouse.ts"],"names":[],"mappings":"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"}