stelo 1.0.1

package/dist/agent.js

@@ -0,0 +1,1107 @@
+"use strict";
+/**
+ * Real-time Agent Control Module
+ *
+ * Designed for low-latency control of mouse and keyboard with:
+ * - Action batching (minimizes round-trips)
+ * - Visual verification (confirms actions had effect)
+ * - Async non-blocking movement (cursor moves visually in real-time)
+ * - Parallel action execution (multiple things at once)
+ * - Streaming cursor control (continuous, cancellable)
+ * - Velocity-based streaming control (continuous, low-latency)
+ * - Gesture recording and playback
+ *
+ * @module agent
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agent = exports.ActionSequence = void 0;
+exports.executeBatch = executeBatch;
+exports.clickAndVerify = clickAndVerify;
+exports.hotkeyAndVerify = hotkeyAndVerify;
+exports.moveRelative = moveRelative;
+exports.moveRelativeSmooth = moveRelativeSmooth;
+exports.typeAndWaitStable = typeAndWaitStable;
+exports.recordMouseTrail = recordMouseTrail;
+exports.replayMouseTrail = replayMouseTrail;
+exports.releaseAllModifiers = releaseAllModifiers;
+exports.sequence = sequence;
+exports.clickAndWait = clickAndWait;
+exports.typeAndEnter = typeAndEnter;
+exports.parallel = parallel;
+exports.createCursorStream = createCursorStream;
+exports.moveClickVerify = moveClickVerify;
+exports.executeBatchAsync = executeBatchAsync;
+exports.smoothClickAt = smoothClickAt;
+exports.smoothClickAndType = smoothClickAndType;
+exports.nativeParallel = nativeParallel;
+exports.interleave = interleave;
+exports.ocr = ocr;
+exports.findText = findText;
+exports.clickText = clickText;
+exports.waitForText = waitForText;
+exports.waitForTextAndClick = waitForTextAndClick;
+exports.watchRegion = watchRegion;
+exports.onRegionChange = onRegionChange;
+exports.onHotkey = onHotkey;
+exports.waitForHotkey = waitForHotkey;
+const index_js_1 = require("../index.js");
+// ─────────────────────────────────────────────────────────────────────────────
+// Core Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Execute multiple actions as an atomic batch.
+ *
+ * This is the primary way applications should interact with the system.
+ * All actions execute sequentially in a single native call,
+ * minimizing latency and round-trips.
+ *
+ * @example
+ * ```typescript
+ * // Click a button, wait for response, then type
+ * const result = await agent.executeBatch([
+ *   { type: 'mouseClickAt', x: 500, y: 300 },
+ *   { type: 'waitForStable', stableMs: 200 },
+ *   { type: 'type', text: 'Hello World' },
+ *   { type: 'keyPress', key: 'Enter' }
+ * ]);
+ *
+ * if (result.allSucceeded) {
+ *   console.log('All actions completed in', result.totalDurationMs, 'ms');
+ * }
+ * ```
+ *
+ * @param actions Array of actions to execute
+ * @param options Execution options
+ * @returns Batch result with per-action details
+ */
+function executeBatch(actions, options = {}) {
+    const nativeResult = (0, index_js_1.agentExecuteBatch)(actions, options.stopOnError ?? true);
+    return {
+        results: nativeResult.results.map((r) => ({
+            index: r.index,
+            success: r.success,
+            error: r.error ?? undefined,
+            durationMs: r.durationMs,
+            mousePosition: r.mouseX != null && r.mouseY != null
+                ? { x: r.mouseX, y: r.mouseY }
+                : undefined,
+            changeDetected: r.changeDetected ?? undefined,
+        })),
+        totalDurationMs: nativeResult.totalDurationMs,
+        successCount: nativeResult.successCount,
+        failureCount: nativeResult.failureCount,
+        firstFailureIndex: nativeResult.firstFailureIndex,
+        allSucceeded: nativeResult.allSucceeded,
+    };
+}
+/**
+ * Click at a position and verify visual change occurred.
+ *
+ * Useful for confirming clicks had an effect.
+ * Captures screen before and after click, computes diff.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.clickAndVerify(500, 300);
+ * if (!result.verified) {
+ *   console.log('Click had no visual effect - may need retry');
+ * }
+ * ```
+ *
+ * @param x Target X coordinate
+ * @param y Target Y coordinate
+ * @param options Click options
+ * @returns Verification result
+ */
+function clickAndVerify(x, y, options = {}) {
+    const result = (0, index_js_1.agentClickAndVerify)(x, y, options.button, options.minChangePercent, options.timeoutMs, options.region?.x, options.region?.y, options.region?.width, options.region?.height);
+    return {
+        verified: result.verified,
+        changePercentage: result.changePercentage,
+        durationMs: result.durationMs,
+    };
+}
+/**
+ * Execute a hotkey combination and verify visual change.
+ *
+ * @example
+ * ```typescript
+ * // Open file dialog and verify it appeared
+ * const result = await agent.hotkeyAndVerify(['ctrl', 'o']);
+ * if (result.verified) {
+ *   console.log('Dialog opened');
+ * }
+ * ```
+ *
+ * @param keys Array of keys to press together
+ * @param options Verification options
+ * @returns Verification result
+ */
+function hotkeyAndVerify(keys, options = {}) {
+    const result = (0, index_js_1.agentHotkeyAndVerify)(keys, options.minChangePercent, options.timeoutMs, options.region?.x, options.region?.y, options.region?.width, options.region?.height);
+    return {
+        verified: result.verified,
+        changePercentage: result.changePercentage,
+        durationMs: result.durationMs,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Relative Mouse Movement
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Move mouse relative to current position.
+ *
+ * @param dx Horizontal offset (positive = right)
+ * @param dy Vertical offset (positive = down)
+ * @returns New mouse position
+ */
+function moveRelative(dx, dy) {
+    const pos = (0, index_js_1.agentMoveRelative)(dx, dy);
+    return { x: pos.x, y: pos.y };
+}
+/**
+ * Move mouse relative to current position with smooth animation.
+ *
+ * @param dx Horizontal offset
+ * @param dy Vertical offset
+ * @param durationMs Animation duration (default: 300ms)
+ * @returns New mouse position
+ */
+function moveRelativeSmooth(dx, dy, durationMs) {
+    const pos = (0, index_js_1.agentMoveRelativeSmooth)(dx, dy, durationMs);
+    return { x: pos.x, y: pos.y };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Text Input with Verification
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Type text and wait for screen to stabilize.
+ *
+ * Useful for form input where you want to wait for
+ * autocomplete or validation to finish.
+ *
+ * @param text Text to type
+ * @param options Wait options
+ * @returns True if screen stabilized within timeout
+ */
+function typeAndWaitStable(text, options = {}) {
+    return (0, index_js_1.agentTypeAndWaitStable)(text, options.stabilityThreshold, options.stableDurationMs, options.timeoutMs);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Gesture Recording
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Record mouse movements for a duration.
+ *
+ * Captures mouse trail for gesture analysis or replay.
+ *
+ * @example
+ * ```typescript
+ * // Record 3 seconds of mouse movement
+ * const trail = agent.recordMouseTrail(3000);
+ * console.log(`Recorded ${trail.length} points`);
+ *
+ * // Replay at half speed
+ * agent.replayMouseTrail(trail, 0.5);
+ * ```
+ *
+ * @param durationMs How long to record
+ * @param sampleRateHz Sample rate (default: 60)
+ * @returns Array of trail points with timestamps
+ */
+function recordMouseTrail(durationMs, sampleRateHz) {
+    const trail = (0, index_js_1.agentRecordMouseTrail)(durationMs, sampleRateHz);
+    return trail.map((p) => ({
+        timestampMs: p.timestampMs,
+        x: p.x,
+        y: p.y,
+    }));
+}
+/**
+ * Replay a recorded mouse trail.
+ *
+ * @param trail Previously recorded trail
+ * @param speedMultiplier Playback speed (1.0 = normal, 0.5 = half speed)
+ */
+function replayMouseTrail(trail, speedMultiplier) {
+    const native = trail.map((p) => ({
+        timestampMs: p.timestampMs,
+        x: p.x,
+        y: p.y,
+    }));
+    (0, index_js_1.agentReplayMouseTrail)(native, speedMultiplier);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Error Recovery
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Release all held modifier keys.
+ *
+ * Call this for error recovery when modifier keys might be stuck,
+ * or after complex keyboard sequences.
+ */
+function releaseAllModifiers() {
+    (0, index_js_1.agentReleaseAllModifiers)();
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Action Builders (Fluent API)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Fluent action builder for creating complex sequences.
+ *
+ * @example
+ * ```typescript
+ * const result = agent.sequence()
+ *   .click(500, 300)
+ *   .waitForStable()
+ *   .type('Hello World')
+ *   .press('Enter')
+ *   .waitForChange()
+ *   .execute();
+ * ```
+ */
+class ActionSequence {
+    actions = [];
+    /** Move mouse to absolute position */
+    moveTo(x, y) {
+        this.actions.push({ type: 'mouseMove', x, y });
+        return this;
+    }
+    /** Move mouse smoothly to absolute position */
+    moveToSmooth(x, y, duration) {
+        this.actions.push({ type: 'mouseMoveSmooth', x, y, duration });
+        return this;
+    }
+    /** Move mouse relative to current position */
+    moveBy(dx, dy) {
+        this.actions.push({ type: 'mouseMoveRel', dx, dy });
+        return this;
+    }
+    /** Click at current position */
+    click(button) {
+        this.actions.push({ type: 'mouseClick', button });
+        return this;
+    }
+    /** Click at specific coordinates */
+    clickAt(x, y, button) {
+        this.actions.push({ type: 'mouseClickAt', x, y, button });
+        return this;
+    }
+    /** Double click */
+    doubleClick(button) {
+        this.actions.push({ type: 'mouseDoubleClick', button });
+        return this;
+    }
+    /** Press mouse button down */
+    mouseDown(button) {
+        this.actions.push({ type: 'mouseDown', button });
+        return this;
+    }
+    /** Release mouse button */
+    mouseUp(button) {
+        this.actions.push({ type: 'mouseUp', button });
+        return this;
+    }
+    /** Scroll wheel */
+    scroll(amount, horizontal) {
+        this.actions.push({ type: 'mouseScroll', amount, horizontal });
+        return this;
+    }
+    /** Drag from current position to target */
+    dragTo(toX, toY, button) {
+        this.actions.push({ type: 'mouseDrag', toX, toY, button });
+        return this;
+    }
+    /** Type text instantly */
+    type(text) {
+        this.actions.push({ type: 'type', text });
+        return this;
+    }
+    /** Type text with human-like delays */
+    typeHuman(text, minDelay, maxDelay) {
+        this.actions.push({ type: 'typeHumanized', text, minDelay, maxDelay });
+        return this;
+    }
+    /** Press and release a key */
+    press(key) {
+        this.actions.push({ type: 'keyPress', key });
+        return this;
+    }
+    /** Press key down (remember to release!) */
+    keyDown(key) {
+        this.actions.push({ type: 'keyDown', key });
+        return this;
+    }
+    /** Release key */
+    keyUp(key) {
+        this.actions.push({ type: 'keyUp', key });
+        return this;
+    }
+    /** Press a hotkey combination */
+    hotkey(...keys) {
+        this.actions.push({ type: 'hotkey', keys });
+        return this;
+    }
+    /** Wait for specified duration */
+    delay(ms) {
+        this.actions.push({ type: 'delay', ms });
+        return this;
+    }
+    /** Alias for delay */
+    wait(ms) {
+        return this.delay(ms);
+    }
+    /** Wait for visual change */
+    waitForChange(options) {
+        this.actions.push({
+            type: 'waitForChange',
+            threshold: options?.threshold,
+            timeout: options?.timeout,
+            region: options?.region,
+        });
+        return this;
+    }
+    /** Wait for screen to stabilize */
+    waitForStable(options) {
+        this.actions.push({
+            type: 'waitForStable',
+            threshold: options?.threshold,
+            stableMs: options?.stableMs,
+            timeout: options?.timeout,
+            region: options?.region,
+        });
+        return this;
+    }
+    /** Get the built actions array */
+    build() {
+        return [...this.actions];
+    }
+    /** Execute all queued actions */
+    execute(options) {
+        return executeBatch(this.actions, options);
+    }
+    /** Execute all queued actions — non-blocking async version */
+    async executeAsync(options) {
+        return executeBatchAsync(this.actions, options);
+    }
+    /** Clear all queued actions */
+    clear() {
+        this.actions = [];
+        return this;
+    }
+}
+exports.ActionSequence = ActionSequence;
+/**
+ * Create a new action sequence builder.
+ *
+ * @example
+ * ```typescript
+ * const result = agent.sequence()
+ *   .clickAt(500, 300)
+ *   .waitForStable()
+ *   .type('search query')
+ *   .press('Enter')
+ *   .execute();
+ * ```
+ */
+function sequence() {
+    return new ActionSequence();
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Convenience Functions
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Simple click with optional wait for visual feedback.
+ * Combines click and waitForStable in one call.
+ *
+ * @param x Target X coordinate
+ * @param y Target Y coordinate
+ * @param options Click options
+ * @returns Batch result
+ */
+function clickAndWait(x, y, options = {}) {
+    return executeBatch([
+        { type: 'mouseClickAt', x, y, button: options.button },
+        { type: 'waitForStable', stableMs: options.stableMs ?? 200 },
+    ]);
+}
+/**
+ * Type text followed by Enter key.
+ *
+ * @param text Text to type before pressing Enter
+ * @param options Type options
+ * @returns Batch result
+ */
+function typeAndEnter(text, options = {}) {
+    const actions = options.humanized
+        ? [{ type: 'typeHumanized', text }, { type: 'keyPress', key: 'Enter' }]
+        : [{ type: 'type', text }, { type: 'keyPress', key: 'Enter' }];
+    return executeBatch(actions);
+}
+/**
+ * Execute multiple independent actions in parallel.
+ *
+ * This is the key primitive for AI agents that need to do multiple things
+ * simultaneously — e.g., move the mouse while monitoring the screen,
+ * or type while watching for visual changes.
+ *
+ * Each task is a named async function. All run concurrently via Promise.all.
+ *
+ * @example
+ * ```typescript
+ * // Move mouse and monitor screen simultaneously
+ * const result = await agent.parallel({
+ *   move: async () => {
+ *     // Non-blocking smooth movement
+ *     const handle = mouse.moveSmoothAsync(500, 300, { duration: 600 });
+ *     return handle.promise;
+ *   },
+ *   monitor: async () => {
+ *     // Capture screen while mouse is moving
+ *     await sleep(200);
+ *     return screen.capture();
+ *   },
+ * });
+ *
+ * // All done
+ * console.log(result.allSucceeded); // true
+ * ```
+ */
+async function parallel(tasks) {
+    const start = Date.now();
+    const names = Object.keys(tasks);
+    const promises = names.map(async (name) => {
+        const taskStart = Date.now();
+        try {
+            const value = await tasks[name]();
+            return {
+                name,
+                success: true,
+                durationMs: Date.now() - taskStart,
+                value,
+            };
+        }
+        catch (err) {
+            return {
+                name,
+                success: false,
+                error: err?.message ?? String(err),
+                durationMs: Date.now() - taskStart,
+            };
+        }
+    });
+    const results = await Promise.all(promises);
+    return {
+        results,
+        totalDurationMs: Date.now() - start,
+        allSucceeded: results.every(r => r.success),
+    };
+}
+/**
+ * Create a real-time cursor control stream.
+ *
+ * Returns a handle that lets you continuously direct the cursor in real-time.
+ * The cursor moves smoothly towards targets with no blocking. Multiple
+ * `moveTo()` calls seamlessly redirect the cursor mid-flight.
+ *
+ * This is the preferred way for AI agents to control the cursor because:
+ * - Movement is always visible and smooth
+ * - Targets can be updated any time (no waiting for previous move to finish)
+ * - Velocity-based control for continuous steering
+ * - Zero blocking of the Node.js event loop
+ *
+ * @param updateRateHz How many times per second to update position (default: 120)
+ *
+ * @example
+ * ```typescript
+ * const cursor = agent.createCursorStream(120);
+ *
+ * // Smooth movement to target
+ * cursor.moveTo(500, 300);
+ *
+ * // Change target mid-flight — cursor redirects smoothly
+ * setTimeout(() => cursor.moveTo(800, 600), 200);
+ *
+ * // Velocity-based control (e.g., from joystick or AI output)
+ * cursor.setVelocity(200, -100); // 200px/s right, 100px/s up
+ *
+ * // When done
+ * cursor.destroy();
+ * ```
+ */
+function createCursorStream(updateRateHz = 120) {
+    let active = true;
+    let targetX = null;
+    let targetY = null;
+    let velocityX = 0;
+    let velocityY = 0;
+    let timer = null;
+    const intervalMs = Math.max(1, Math.round(1000 / updateRateHz));
+    // The update loop runs on a setInterval — non-blocking
+    timer = setInterval(() => {
+        if (!active)
+            return;
+        try {
+            const pos = (0, index_js_1.mouseGetPosition)();
+            if (targetX !== null && targetY !== null) {
+                const dx = targetX - pos.x;
+                const dy = targetY - pos.y;
+                const dist = Math.sqrt(dx * dx + dy * dy);
+                if (dist < 2) {
+                    // Arrived at target
+                    (0, index_js_1.mouseMove)(targetX, targetY);
+                    targetX = null;
+                    targetY = null;
+                }
+                else {
+                    // Move towards target — speed proportional to distance
+                    const speed = Math.min(3000, dist * 6);
+                    const moveX = Math.round((dx / dist) * speed / updateRateHz);
+                    const moveY = Math.round((dy / dist) * speed / updateRateHz);
+                    (0, index_js_1.mouseMove)(pos.x + moveX, pos.y + moveY);
+                }
+            }
+            else if (velocityX !== 0 || velocityY !== 0) {
+                // Velocity-based movement
+                const moveX = Math.round(velocityX / updateRateHz);
+                const moveY = Math.round(velocityY / updateRateHz);
+                if (moveX !== 0 || moveY !== 0) {
+                    (0, index_js_1.mouseMove)(pos.x + moveX, pos.y + moveY);
+                }
+            }
+        }
+        catch {
+            // Silently continue on error (e.g., if mouse API fails momentarily)
+        }
+    }, intervalMs);
+    const handle = {
+        moveTo(x, y) {
+            targetX = x;
+            targetY = y;
+            velocityX = 0;
+            velocityY = 0;
+        },
+        jumpTo(x, y) {
+            targetX = null;
+            targetY = null;
+            velocityX = 0;
+            velocityY = 0;
+            (0, index_js_1.mouseMove)(x, y);
+        },
+        setVelocity(vx, vy) {
+            velocityX = vx;
+            velocityY = vy;
+            targetX = null;
+            targetY = null;
+        },
+        stop() {
+            targetX = null;
+            targetY = null;
+            velocityX = 0;
+            velocityY = 0;
+        },
+        destroy() {
+            active = false;
+            if (timer !== null) {
+                clearInterval(timer);
+                timer = null;
+            }
+        },
+        get active() { return active; },
+        get position() {
+            const p = (0, index_js_1.mouseGetPosition)();
+            return { x: p.x, y: p.y };
+        },
+    };
+    return handle;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Non-Blocking Agent Primitives
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Move to a position smoothly, click, and verify — all non-blocking.
+ *
+ * The cursor visually moves to the target, clicks, then verifies
+ * that the screen changed. The entire operation is async.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.moveClickVerify(500, 300, {
+ *   moveDuration: 400,
+ *   button: 'left',
+ * });
+ * console.log(result.verified); // true if screen changed after click
+ * ```
+ */
+async function moveClickVerify(x, y, options = {}) {
+    // Non-blocking smooth movement
+    const from = (0, index_js_1.mouseGetPosition)();
+    const duration = options.moveDuration ?? 400;
+    const steps = Math.max(2, Math.round((120 * duration) / 1000));
+    const delayMs = Math.max(1, Math.round(duration / steps));
+    // Simple easing path
+    const dx = x - from.x;
+    const dy = y - from.y;
+    for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const e = t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+        (0, index_js_1.mouseMove)(Math.round(from.x + dx * e), Math.round(from.y + dy * e));
+        await new Promise(r => setTimeout(r, delayMs));
+    }
+    // Click and verify
+    const result = clickAndVerify(x, y, {
+        button: options.button,
+        minChangePercent: options.minChangePercent,
+        timeoutMs: options.verifyTimeoutMs,
+        region: options.region,
+    });
+    return {
+        ...result,
+        finalPosition: { x, y },
+    };
+}
+/**
+ * Execute a batch of actions with async wrapper.
+ *
+ * Same as `executeBatch()` but returns a Promise, so it can be used
+ * in `Promise.all()` with other async operations.
+ */
+async function executeBatchAsync(actions, options = {}) {
+    // Run the synchronous batch in a microtask to allow interleaving
+    return new Promise((resolve) => {
+        setImmediate(() => {
+            resolve(executeBatch(actions, options));
+        });
+    });
+}
+/**
+ * Convenience: smoothly move to position and click — async.
+ * The cursor is visible moving on screen the whole time.
+ */
+async function smoothClickAt(x, y, options = {}) {
+    const from = (0, index_js_1.mouseGetPosition)();
+    const duration = options.duration ?? 350;
+    const steps = Math.max(2, Math.round((120 * duration) / 1000));
+    const delayMs = Math.max(1, Math.round(duration / steps));
+    const dx = x - from.x;
+    const dy = y - from.y;
+    for (let i = 1; i <= steps; i++) {
+        const t = i / steps;
+        const e = t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+        (0, index_js_1.mouseMove)(Math.round(from.x + dx * e), Math.round(from.y + dy * e));
+        if (i < steps)
+            await new Promise(r => setTimeout(r, delayMs));
+    }
+    (0, index_js_1.mouseClick)(options.button);
+}
+/**
+ * Convenience: smoothly move to a text field, click it, type text.
+ * Fully async and visually smooth.
+ */
+async function smoothClickAndType(x, y, text, options = {}) {
+    await smoothClickAt(x, y, { duration: options.duration });
+    await new Promise(r => setTimeout(r, 50));
+    (0, index_js_1.keyboardType)(text, options.typeDelay);
+}
+/**
+ * Execute multiple action groups in TRUE parallel on native OS threads.
+ *
+ * Each group runs on its own Rust thread. Within a group, actions execute
+ * sequentially. Groups start simultaneously (or with optional start delays).
+ *
+ * This is the core primitive that makes Stelo faster than any other SDK —
+ * true OS-level parallelism, not async pretend.
+ *
+ * @example
+ * ```typescript
+ * // Move mouse AND type AND capture screen — all at the same time
+ * const result = agent.nativeParallel([
+ *   {
+ *     groupId: 'mouse',
+ *     actions: [
+ *       { type: 'mouseMoveSmooth', x: 500, y: 300, duration: 500 },
+ *       { type: 'mouseClick' },
+ *     ],
+ *   },
+ *   {
+ *     groupId: 'keyboard',
+ *     actions: [
+ *       { type: 'delay', ms: 200 },  // Start typing 200ms after mouse starts
+ *       { type: 'type', text: 'hello world' },
+ *     ],
+ *   },
+ * ]);
+ * console.log(result.totalDurationMs); // ~500ms, not ~700ms sequential
+ * ```
+ */
+function nativeParallel(groups) {
+    const nativeResult = (0, index_js_1.parallelExecute)(groups);
+    return mapParallelResult(nativeResult);
+}
+/**
+ * Execute actions with interleaved timing — human-like overlapping input.
+ *
+ * Each action has a startAtMs offset. Actions with the same start time
+ * run in parallel on separate OS threads. This enables realistic
+ * overlapping mouse + keyboard behavior.
+ *
+ * @example
+ * ```typescript
+ * // Start moving mouse immediately, start typing while mouse still moving
+ * agent.interleave([
+ *   { startAtMs: 0, type: 'mouseMoveSmooth', x: 500, y: 300, duration: 500 },
+ *   { startAtMs: 150, type: 'type', text: 'hello' },  // starts while mouse moving
+ *   { startAtMs: 500, type: 'mouseClick' },             // after mouse arrives
+ * ]);
+ * ```
+ */
+function interleave(timedActions) {
+    const nativeResult = (0, index_js_1.interleavedExecute)(timedActions);
+    return mapParallelResult(nativeResult);
+}
+function mapParallelResult(nr) {
+    return {
+        groups: nr.groups.map((g) => ({
+            groupId: g.groupId,
+            results: g.results.map((r) => ({
+                index: r.index,
+                success: r.success,
+                error: r.error ?? undefined,
+                durationMs: r.durationMs,
+                mousePosition: r.mouseX != null && r.mouseY != null
+                    ? { x: r.mouseX, y: r.mouseY }
+                    : undefined,
+                changeDetected: r.changeDetected ?? undefined,
+            })),
+            durationMs: g.durationMs,
+            successCount: g.successCount,
+            failureCount: g.failureCount,
+        })),
+        totalDurationMs: nr.totalDurationMs,
+        totalActions: nr.totalActions,
+        totalSuccess: nr.totalSuccess,
+        totalFailures: nr.totalFailures,
+        allSucceeded: nr.allSucceeded,
+    };
+}
+/**
+ * Perform OCR on a screen region. Returns recognized text with positions.
+ *
+ * @example
+ * ```typescript
+ * // OCR the entire screen
+ * const result = agent.ocr();
+ * console.log(result.text);
+ *
+ * // OCR a specific region
+ * const result = agent.ocr({ x: 100, y: 200, width: 400, height: 50 });
+ * for (const word of result.lines[0]?.words ?? []) {
+ *   console.log(`"${word.text}" at (${word.center.x}, ${word.center.y})`);
+ * }
+ * ```
+ */
+function ocr(region) {
+    const raw = (0, index_js_1.ocrRecognize)(region?.x, region?.y, region?.width, region?.height);
+    return {
+        text: raw.text,
+        durationMs: raw.durationMs,
+        lines: raw.lines.map((line) => ({
+            text: line.text,
+            x: line.x,
+            y: line.y,
+            width: line.width,
+            height: line.height,
+            words: line.words.map((w) => ({
+                text: w.text,
+                x: w.x,
+                y: w.y,
+                width: w.width,
+                height: w.height,
+                confidence: w.confidence,
+                center: { x: w.x + w.width / 2, y: w.y + w.height / 2 },
+            })),
+        })),
+    };
+}
+/**
+ * Find text on screen via OCR and return its position.
+ *
+ * @example
+ * ```typescript
+ * const submit = agent.findText('Submit');
+ * if (submit) {
+ *   mouse.clickAt(submit.center.x, submit.center.y);
+ * }
+ * ```
+ */
+function findText(needle, region) {
+    const raw = (0, index_js_1.ocrFindText)(needle, region?.x, region?.y, region?.width, region?.height);
+    if (!raw)
+        return null;
+    return {
+        text: raw.text,
+        x: raw.x,
+        y: raw.y,
+        width: raw.width,
+        height: raw.height,
+        confidence: raw.confidence,
+        center: { x: raw.x + raw.width / 2, y: raw.y + raw.height / 2 },
+    };
+}
+/**
+ * Find text on screen and click its center. Game-changer for AI agents.
+ *
+ * @example
+ * ```typescript
+ * // Click the "Submit" button — no coordinates needed
+ * agent.clickText('Submit');
+ *
+ * // Click "Cancel" with right-click
+ * agent.clickText('Cancel', { button: 'right' });
+ * ```
+ *
+ * @throws Error if text not found on screen
+ */
+function clickText(needle, options = {}) {
+    const pos = (0, index_js_1.ocrClickText)(needle, options.button, options.region?.x, options.region?.y, options.region?.width, options.region?.height);
+    return { x: pos.x, y: pos.y };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Smart Reactions — Wait for visual/text conditions before acting
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Wait until OCR detects the specified text on screen.
+ * Polls at a configurable interval. Returns the word position, or null on timeout.
+ *
+ * @example
+ * ```typescript
+ * // Wait up to 10s for "Loading complete" to appear
+ * const word = agent.waitForText('Loading complete', { timeout: 10000 });
+ * if (word) console.log('Found at', word.center);
+ * ```
+ */
+function waitForText(needle, options = {}) {
+    const raw = (0, index_js_1.waitForText)(needle, options.timeout, options.interval, options.region?.x, options.region?.y, options.region?.width, options.region?.height);
+    if (!raw)
+        return null;
+    return {
+        text: raw.text,
+        x: raw.x,
+        y: raw.y,
+        width: raw.width,
+        height: raw.height,
+        confidence: raw.confidence,
+        center: { x: raw.x + raw.width / 2, y: raw.y + raw.height / 2 },
+    };
+}
+/**
+ * Wait for text to appear on screen, then click it.
+ * Combines waitForText + click in a single native call for lower latency.
+ *
+ * @example
+ * ```typescript
+ * // Wait for "Submit" button to appear, then click it
+ * const pos = agent.waitForTextAndClick('Submit', { timeout: 5000 });
+ * if (pos) console.log('Clicked at', pos);
+ * ```
+ */
+function waitForTextAndClick(needle, options = {}) {
+    const raw = (0, index_js_1.waitForTextAndClick)(needle, options.timeout, options.interval, options.button, options.region?.x, options.region?.y, options.region?.width, options.region?.height);
+    return raw ? { x: raw.x, y: raw.y } : null;
+}
+/**
+ * Watch a screen region and wait for it to change.
+ * Returns the change percentage when threshold is exceeded, or null on timeout.
+ *
+ * @example
+ * ```typescript
+ * // Watch a button area for any visual change
+ * const change = agent.watchRegion(
+ *   { x: 200, y: 300, width: 100, height: 40 },
+ *   { threshold: 2.0, timeout: 5000 }
+ * );
+ * if (change) console.log(`Region changed by ${change.toFixed(1)}%`);
+ * ```
+ */
+function watchRegion(region, options = {}) {
+    return (0, index_js_1.watchRegionOnce)(region.x, region.y, region.width, region.height, options.threshold, options.timeout, options.interval);
+}
+/**
+ * Continuously watch a screen region and call a handler when it changes.
+ * Returns a stop function.
+ *
+ * @example
+ * ```typescript
+ * const stop = agent.onRegionChange(
+ *   { x: 200, y: 300, width: 100, height: 40 },
+ *   (changePct) => console.log(`Changed: ${changePct}%`),
+ *   { threshold: 1.0, interval: 300 }
+ * );
+ * // Later...
+ * stop();
+ * ```
+ */
+function onRegionChange(region, handler, options = {}) {
+    let running = true;
+    const interval = options.interval ?? 300;
+    const threshold = options.threshold ?? 1.0;
+    const poll = () => {
+        if (!running)
+            return;
+        const change = (0, index_js_1.watchRegionOnce)(region.x, region.y, region.width, region.height, threshold, interval + 100, // slight timeout buffer
+        interval);
+        if (change !== null && running) {
+            handler(change);
+        }
+        if (running) {
+            setTimeout(poll, 0);
+        }
+    };
+    setTimeout(poll, 0);
+    return () => { running = false; };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Hotkey System — Register global keyboard shortcuts
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Register a global hotkey handler. Starts listening for keyboard events
+ * and triggers the callback when the key combination is detected.
+ *
+ * @example
+ * ```typescript
+ * // Register Ctrl+Shift+A
+ * const unregister = agent.onHotkey('ctrl+shift+a', () => {
+ *   console.log('Hotkey triggered!');
+ * });
+ *
+ * // Later: stop listening
+ * unregister();
+ * ```
+ */
+function onHotkey(combo, handler, options = {}) {
+    // Parse combo: "ctrl+shift+a" → { ctrl: true, shift: true, alt: false, key: 'a' }
+    const parts = combo.toLowerCase().split('+').map(s => s.trim());
+    const modifiers = {
+        ctrl: parts.includes('ctrl') || parts.includes('control'),
+        shift: parts.includes('shift'),
+        alt: parts.includes('alt'),
+        meta: parts.includes('meta') || parts.includes('win') || parts.includes('cmd'),
+    };
+    const key = parts.find(p => !['ctrl', 'control', 'shift', 'alt', 'meta', 'win', 'cmd'].includes(p)) || '';
+    let running = true;
+    const pollMs = options.pollInterval ?? 50;
+    // Use hooks to poll for key events
+    const { startHooks, drainEvents, stopHooks } = require('../index.js');
+    startHooks({ captureKeyboard: true, captureMouseClicks: false, captureMouseMove: false, captureMouseWheel: false, bufferSize: 64 });
+    const held = new Set();
+    const poll = () => {
+        if (!running)
+            return;
+        try {
+            const events = drainEvents();
+            for (const ev of events) {
+                if (ev.type === 'keydown' || ev.type === 'KeyDown') {
+                    held.add((ev.keyName || '').toLowerCase());
+                }
+                else if (ev.type === 'keyup' || ev.type === 'KeyUp') {
+                    held.delete((ev.keyName || '').toLowerCase());
+                }
+                // Check if combo matches on keydown
+                if (ev.type === 'keydown' || ev.type === 'KeyDown') {
+                    const keyMatch = key === '' || (ev.keyName || '').toLowerCase() === key;
+                    const ctrlMatch = !modifiers.ctrl || held.has('lcontrol') || held.has('rcontrol') || held.has('control');
+                    const shiftMatch = !modifiers.shift || held.has('lshift') || held.has('rshift') || held.has('shift');
+                    const altMatch = !modifiers.alt || held.has('lalt') || held.has('ralt') || held.has('alt') || held.has('lmenu') || held.has('rmenu');
+                    if (keyMatch && ctrlMatch && shiftMatch && altMatch) {
+                        handler();
+                    }
+                }
+            }
+        }
+        catch { /* ignore errors during polling */ }
+        if (running)
+            setTimeout(poll, pollMs);
+    };
+    setTimeout(poll, 0);
+    return () => {
+        running = false;
+        try {
+            stopHooks();
+        }
+        catch { /* ignore */ }
+    };
+}
+/**
+ * Wait for a hotkey combo to be pressed. Returns a promise that resolves
+ * when the combo is detected, or rejects on timeout.
+ *
+ * @example
+ * ```typescript
+ * await agent.waitForHotkey('ctrl+shift+s', { timeout: 30000 });
+ * console.log('User pressed Ctrl+Shift+S!');
+ * ```
+ */
+function waitForHotkey(combo, options = {}) {
+    const timeout = options.timeout ?? 30000;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            unregister();
+            reject(new Error(`Hotkey '${combo}' not pressed within ${timeout}ms`));
+        }, timeout);
+        const unregister = onHotkey(combo, () => {
+            clearTimeout(timer);
+            unregister();
+            resolve();
+        });
+    });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Default Export
+// ─────────────────────────────────────────────────────────────────────────────
+exports.agent = {
+    // Core
+    executeBatch,
+    executeBatchAsync,
+    clickAndVerify,
+    hotkeyAndVerify,
+    // Async / Non-blocking
+    parallel,
+    moveClickVerify,
+    smoothClickAt,
+    smoothClickAndType,
+    // Streaming control
+    createCursorStream,
+    // Relative movement
+    moveRelative,
+    moveRelativeSmooth,
+    // Text input
+    typeAndWaitStable,
+    // Gesture
+    recordMouseTrail,
+    replayMouseTrail,
+    // Recovery
+    releaseAllModifiers,
+    // Fluent API
+    sequence,
+    ActionSequence,
+    // Convenience
+    clickAndWait,
+    typeAndEnter,
+    // Native Parallel Pipeline (true OS-thread parallelism)
+    nativeParallel,
+    interleave,
+    // OCR (native text recognition)
+    ocr,
+    findText,
+    clickText,
+    // Smart Reactions
+    waitForText,
+    waitForTextAndClick,
+    watchRegion,
+    onRegionChange,
+    // Hotkey System
+    onHotkey,
+    waitForHotkey,
+};
+exports.default = exports.agent;
+//# sourceMappingURL=agent.js.map