stelo 1.0.1

package/dist/keyboard.d.ts

@@ -0,0 +1,276 @@
+import type { TypeOptions, HumanizedTypeOptions } from './types';
+/** Options for key sequence execution */
+export interface KeySequenceOptions {
+    /** Delay between actions in ms (default: 100) */
+    delay?: number;
+}
+/** Options for waiting for a key */
+export interface WaitForKeyOptions {
+    /** Timeout in ms (default: 30000) */
+    timeout?: number;
+}
+/**
+ * Keyboard control interface — the most advanced keyboard automation API.
+ *
+ * @example
+ * ```typescript
+ * import { keyboard } from 'stelo';
+ *
+ * // Type text (character by character)
+ * keyboard.type('Hello World!');
+ *
+ * // Batch type (10-100x faster, single OS call)
+ * keyboard.typeBatch('Entire string typed instantly');
+ *
+ * // Keyboard shortcut (individual arguments)
+ * keyboard.hotkey('ctrl', 'c');
+ *
+ * // Hotkey from string
+ * keyboard.hotkeyString('ctrl+shift+s');
+ *
+ * // Key sequence macro
+ * keyboard.sequence('ctrl+a | ctrl+c | alt+tab | ctrl+v');
+ *
+ * // Type with modifiers held
+ * keyboard.typeWithModifiers('hello', 'shift'); // Types "HELLO"
+ *
+ * // Wait for a key press
+ * const pressed = keyboard.waitForKey('escape', { timeout: 5000 });
+ *
+ * // Check toggle state
+ * const capsOn = keyboard.isToggled('capslock');
+ * ```
+ */
+export declare const keyboard: {
+    /**
+     * Type a text string, character by character.
+     * Supports full Unicode including emoji and international characters.
+     */
+    type(text: string, options?: TypeOptions): void;
+    /**
+     * Type text with randomized human-like delays between characters.
+     */
+    typeHumanized(text: string, options?: HumanizedTypeOptions): void;
+    /**
+     * Type an entire string in a single atomic OS call.
+     * 10-100x faster than character-by-character typing.
+     * All characters are batched in one SendInput call — no inter-character delay.
+     *
+     * Best for: filling forms, pasting large text, programmatic input.
+     * For human-like typing, use `type()` or `typeHumanized()` instead.
+     *
+     * @example
+     * ```typescript
+     * keyboard.typeBatch('This entire sentence is typed in one OS call');
+     * ```
+     */
+    typeBatch(text: string): void;
+    /**
+     * Type text while holding modifier keys down.
+     *
+     * @example
+     * ```typescript
+     * keyboard.typeWithModifiers('hello', 'shift');         // Types "HELLO"
+     * keyboard.typeWithModifiers('abc', 'ctrl', 'shift');   // Ctrl+Shift held
+     * ```
+     */
+    typeWithModifiers(text: string, ...modifiers: string[]): void;
+    /**
+     * Press and release a single key.
+     *
+     * Supported key names include:
+     * - Letters: 'a'–'z'
+     * - Digits: '0'–'9'
+     * - Modifiers: 'shift', 'ctrl'/'control', 'alt', 'meta'/'win'/'cmd'
+     * - Navigation: 'up', 'down', 'left', 'right', 'home', 'end', 'pageup', 'pagedown'
+     * - Editing: 'enter', 'tab', 'space', 'backspace', 'delete', 'escape'
+     * - Function: 'f1'–'f24'
+     * - And many more — see `keyboard.allKeys()` for the full list.
+     */
+    press(key: string): void;
+    /**
+     * Hold a key down (without releasing).
+     */
+    down(key: string): void;
+    /**
+     * Release a held key.
+     */
+    up(key: string): void;
+    /**
+     * Press a key multiple times.
+     * @param key - Key to press
+     * @param count - Number of times (default: 1)
+     * @param delay - Delay between presses in ms (default: 50)
+     */
+    tap(key: string, count?: number, delay?: number): void;
+    /**
+     * Execute a keyboard shortcut.
+     * Keys are pressed in order and released in reverse order.
+     *
+     * @example
+     * ```typescript
+     * keyboard.hotkey('ctrl', 'c');           // Copy
+     * keyboard.hotkey('ctrl', 'shift', 's');  // Save As
+     * keyboard.hotkey('alt', 'f4');           // Close window
+     * ```
+     */
+    hotkey(...keys: string[]): void;
+    /**
+     * Execute a hotkey from a single string like "ctrl+shift+s".
+     * More convenient for dynamic/programmatic use.
+     *
+     * @example
+     * ```typescript
+     * keyboard.hotkeyString('ctrl+c');
+     * keyboard.hotkeyString('ctrl+shift+s');
+     * keyboard.hotkeyString('alt+f4');
+     * ```
+     */
+    hotkeyString(combo: string): void;
+    /**
+     * Execute a sequence of keyboard actions separated by '|'.
+     *
+     * Each action can be:
+     *   - A hotkey combo: `"ctrl+c"`
+     *   - A single key press: `"enter"`
+     *   - Literal text to type: `"type:Hello World"`
+     *
+     * @example
+     * ```typescript
+     * // Select all → Copy → Switch window → Paste
+     * keyboard.sequence('ctrl+a | ctrl+c | alt+tab | ctrl+v');
+     *
+     * // Open file dialog, type filename, press enter
+     * keyboard.sequence('ctrl+o | type:document.txt | enter');
+     *
+     * // With custom delay between actions
+     * keyboard.sequence('tab | tab | enter', { delay: 50 });
+     * ```
+     */
+    sequence(sequence: string, options?: KeySequenceOptions): void;
+    /**
+     * Check if a key is currently held down.
+     */
+    isPressed(key: string): boolean;
+    /**
+     * Check multiple keys at once.
+     * Returns an array of booleans matching the input keys.
+     *
+     * @example
+     * ```typescript
+     * const [ctrl, shift, alt] = keyboard.arePressed('ctrl', 'shift', 'alt');
+     * if (ctrl && !shift) { ... }
+     * ```
+     */
+    arePressed(...keys: string[]): boolean[];
+    /**
+     * Check if a toggle key (CapsLock, NumLock, ScrollLock) is ON.
+     *
+     * @example
+     * ```typescript
+     * if (keyboard.isToggled('capslock')) {
+     *   console.log('CapsLock is ON');
+     * }
+     * ```
+     */
+    isToggled(key: string): boolean;
+    /**
+     * Toggle a lock key (CapsLock, NumLock, ScrollLock).
+     * Sends a press+release to flip the toggle state.
+     */
+    toggleKey(key: string): void;
+    /**
+     * Wait until a specific key is pressed (blocking).
+     * Returns true if pressed, false if timed out.
+     *
+     * @example
+     * ```typescript
+     * console.log('Press Escape to continue...');
+     * keyboard.waitForKey('escape', { timeout: 10000 });
+     * ```
+     */
+    waitForKey(key: string, options?: WaitForKeyOptions): boolean;
+    /**
+     * Wait until a specific key is released (blocking).
+     * Useful after `waitForKey` to detect key-up.
+     */
+    waitForKeyRelease(key: string, options?: WaitForKeyOptions): boolean;
+    /**
+     * Get a list of all recognized key names.
+     */
+    allKeys(): string[];
+    /** Press Enter */
+    enter(): void;
+    /** Press Tab */
+    tab(): void;
+    /** Press Escape */
+    escape(): void;
+    /** Press Backspace */
+    backspace(count?: number): void;
+    /** Press Delete */
+    delete(count?: number): void;
+    /** Select all (Ctrl+A / Cmd+A) */
+    selectAll(): void;
+    /** Copy (Ctrl+C / Cmd+C) */
+    copy(): void;
+    /** Paste (Ctrl+V / Cmd+V) */
+    paste(): void;
+    /** Cut (Ctrl+X / Cmd+X) */
+    cut(): void;
+    /** Undo (Ctrl+Z / Cmd+Z) */
+    undo(): void;
+    /** Redo (Ctrl+Shift+Z / Cmd+Shift+Z) */
+    redo(): void;
+    /** Save (Ctrl+S / Cmd+S) */
+    save(): void;
+    /** Find (Ctrl+F / Cmd+F) */
+    find(): void;
+    /** New (Ctrl+N / Cmd+N) */
+    "new"(): void;
+    /** Close tab/window (Ctrl+W / Cmd+W) */
+    close(): void;
+    /** Print (Ctrl+P / Cmd+P) */
+    print(): void;
+    /** Switch application (Alt+Tab / Cmd+Tab) */
+    switchApp(): void;
+    /**
+     * Type text character-by-character — **non-blocking**.
+     *
+     * Unlike `type()` which blocks the thread, this yields to the event loop
+     * between each character. Other code (screen monitoring, mouse movement)
+     * can run in parallel while text is being typed.
+     *
+     * Returns a cancellable handle.
+     *
+     * @example
+     * ```typescript
+     * // Await completion
+     * await keyboard.typeAsync('Hello World!', { delay: 30 });
+     *
+     * // Cancel mid-type
+     * const handle = keyboard.typeAsync('Long text...');
+     * setTimeout(() => handle.cancel(), 500);
+     * await handle.promise;
+     * ```
+     */
+    typeAsync(text: string, options?: {
+        delay?: number;
+    }): {
+        promise: Promise<void>;
+        cancel: () => void;
+    };
+    /**
+     * Type text with human-like random delays — **non-blocking**.
+     *
+     * Each character is typed with a random delay between minDelay and maxDelay.
+     * Non-blocking: the event loop is free between characters.
+     */
+    typeHumanizedAsync(text: string, options?: {
+        minDelay?: number;
+        maxDelay?: number;
+    }): {
+        promise: Promise<void>;
+        cancel: () => void;
+    };
+};
+//# sourceMappingURL=keyboard.d.ts.map

package/dist/keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.d.ts","sourceRoot":"","sources":["../ts/keyboard.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAIjE,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,QAAQ;IAGnB;;;OAGG;eACQ,MAAM,YAAY,WAAW,GAAG,IAAI;IAI/C;;OAEG;wBACiB,MAAM,YAAY,oBAAoB,GAAG,IAAI;IAQjE;;;;;;;;;;;;OAYG;oBACa,MAAM,GAAG,IAAI;IAI7B;;;;;;;;OAQG;4BACqB,MAAM,gBAAgB,MAAM,EAAE,GAAG,IAAI;IAM7D;;;;;;;;;;;OAWG;eACQ,MAAM,GAAG,IAAI;IAIxB;;OAEG;cACO,MAAM,GAAG,IAAI;IAIvB;;OAEG;YACK,MAAM,GAAG,IAAI;IAIrB;;;;;OAKG;aACM,MAAM,UAAU,MAAM,UAAU,MAAM,GAAG,IAAI;IAMtD;;;;;;;;;;OAUG;oBACa,MAAM,EAAE,GAAG,IAAI;IAI/B;;;;;;;;;;OAUG;wBACiB,MAAM,GAAG,IAAI;IAMjC;;;;;;;;;;;;;;;;;;;OAmBG;uBACgB,MAAM,YAAY,kBAAkB,GAAG,IAAI;IAM9D;;OAEG;mBACY,MAAM,GAAG,OAAO;IAI/B;;;;;;;;;OASG;wBACiB,MAAM,EAAE,GAAG,OAAO,EAAE;IAIxC;;;;;;;;;OASG;mBACY,MAAM,GAAG,OAAO;IAI/B;;;OAGG;mBACY,MAAM,GAAG,IAAI;IAM5B;;;;;;;;;OASG;oBACa,MAAM,YAAY,iBAAiB,GAAG,OAAO;IAI7D;;;OAGG;2BACoB,MAAM,YAAY,iBAAiB,GAAG,OAAO;IAMpE;;OAEG;eACQ,MAAM,EAAE;IAMnB,kBAAkB;aACT,IAAI;IAIb,gBAAgB;WACT,IAAI;IAIX,mBAAmB;cACT,IAAI;IAId,sBAAsB;sBACL,MAAM,GAAO,IAAI;IAIlC,mBAAmB;mBACL,MAAM,GAAO,IAAI;IAI/B,kCAAkC;iBACrB,IAAI;IAIjB,4BAA4B;YACpB,IAAI;IAIZ,6BAA6B;aACpB,IAAI;IAIb,2BAA2B;WACpB,IAAI;IAIX,4BAA4B;YACpB,IAAI;IAIZ,wCAAwC;YAChC,IAAI;IAIZ,4BAA4B;YACpB,IAAI;IAIZ,4BAA4B;YACpB,IAAI;IAIZ,2BAA2B;aACpB,IAAI;IAIX,wCAAwC;aAC/B,IAAI;IAIb,6BAA6B;aACpB,IAAI;IAIb,6CAA6C;iBAChC,IAAI;IAUjB;;;;;;;;;;;;;;;;;;;OAmBG;oBAEK,MAAM,YACF;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC3B;QAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,IAAI,CAAA;KAAE;IA6BjD;;;;;OAKG;6BAEK,MAAM,YACF;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GACjD;QAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,IAAI,CAAA;KAAE;CA6BlD,CAAC"}

package/dist/keyboard.js

@@ -0,0 +1,404 @@
+"use strict";
+// ============================================================================
+// Stelo — Keyboard Control API
+// ============================================================================
+// Full keyboard automation: typing, hotkeys, batch operations, key sequences,
+// toggle detection, modifier-aware typing, and key wait primitives.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyboard = void 0;
+const native = require('../index.js');
+/**
+ * Keyboard control interface — the most advanced keyboard automation API.
+ *
+ * @example
+ * ```typescript
+ * import { keyboard } from 'stelo';
+ *
+ * // Type text (character by character)
+ * keyboard.type('Hello World!');
+ *
+ * // Batch type (10-100x faster, single OS call)
+ * keyboard.typeBatch('Entire string typed instantly');
+ *
+ * // Keyboard shortcut (individual arguments)
+ * keyboard.hotkey('ctrl', 'c');
+ *
+ * // Hotkey from string
+ * keyboard.hotkeyString('ctrl+shift+s');
+ *
+ * // Key sequence macro
+ * keyboard.sequence('ctrl+a | ctrl+c | alt+tab | ctrl+v');
+ *
+ * // Type with modifiers held
+ * keyboard.typeWithModifiers('hello', 'shift'); // Types "HELLO"
+ *
+ * // Wait for a key press
+ * const pressed = keyboard.waitForKey('escape', { timeout: 5000 });
+ *
+ * // Check toggle state
+ * const capsOn = keyboard.isToggled('capslock');
+ * ```
+ */
+exports.keyboard = {
+    // ── Core Typing ─────────────────────────────────────────────────────────
+    /**
+     * Type a text string, character by character.
+     * Supports full Unicode including emoji and international characters.
+     */
+    type(text, options) {
+        native.keyboardType(text, options?.delay ?? undefined);
+    },
+    /**
+     * Type text with randomized human-like delays between characters.
+     */
+    typeHumanized(text, options) {
+        native.keyboardTypeHumanized(text, options?.minDelay ?? undefined, options?.maxDelay ?? undefined);
+    },
+    /**
+     * Type an entire string in a single atomic OS call.
+     * 10-100x faster than character-by-character typing.
+     * All characters are batched in one SendInput call — no inter-character delay.
+     *
+     * Best for: filling forms, pasting large text, programmatic input.
+     * For human-like typing, use `type()` or `typeHumanized()` instead.
+     *
+     * @example
+     * ```typescript
+     * keyboard.typeBatch('This entire sentence is typed in one OS call');
+     * ```
+     */
+    typeBatch(text) {
+        native.keyboardTypeBatch(text);
+    },
+    /**
+     * Type text while holding modifier keys down.
+     *
+     * @example
+     * ```typescript
+     * keyboard.typeWithModifiers('hello', 'shift');         // Types "HELLO"
+     * keyboard.typeWithModifiers('abc', 'ctrl', 'shift');   // Ctrl+Shift held
+     * ```
+     */
+    typeWithModifiers(text, ...modifiers) {
+        native.keyboardTypeWithModifiers(text, modifiers);
+    },
+    // ── Key Press/Release ───────────────────────────────────────────────────
+    /**
+     * Press and release a single key.
+     *
+     * Supported key names include:
+     * - Letters: 'a'–'z'
+     * - Digits: '0'–'9'
+     * - Modifiers: 'shift', 'ctrl'/'control', 'alt', 'meta'/'win'/'cmd'
+     * - Navigation: 'up', 'down', 'left', 'right', 'home', 'end', 'pageup', 'pagedown'
+     * - Editing: 'enter', 'tab', 'space', 'backspace', 'delete', 'escape'
+     * - Function: 'f1'–'f24'
+     * - And many more — see `keyboard.allKeys()` for the full list.
+     */
+    press(key) {
+        native.keyboardPress(key);
+    },
+    /**
+     * Hold a key down (without releasing).
+     */
+    down(key) {
+        native.keyboardDown(key);
+    },
+    /**
+     * Release a held key.
+     */
+    up(key) {
+        native.keyboardUp(key);
+    },
+    /**
+     * Press a key multiple times.
+     * @param key - Key to press
+     * @param count - Number of times (default: 1)
+     * @param delay - Delay between presses in ms (default: 50)
+     */
+    tap(key, count, delay) {
+        native.keyboardTap(key, count, delay);
+    },
+    // ── Hotkeys & Combos ────────────────────────────────────────────────────
+    /**
+     * Execute a keyboard shortcut.
+     * Keys are pressed in order and released in reverse order.
+     *
+     * @example
+     * ```typescript
+     * keyboard.hotkey('ctrl', 'c');           // Copy
+     * keyboard.hotkey('ctrl', 'shift', 's');  // Save As
+     * keyboard.hotkey('alt', 'f4');           // Close window
+     * ```
+     */
+    hotkey(...keys) {
+        native.keyboardHotkey(keys);
+    },
+    /**
+     * Execute a hotkey from a single string like "ctrl+shift+s".
+     * More convenient for dynamic/programmatic use.
+     *
+     * @example
+     * ```typescript
+     * keyboard.hotkeyString('ctrl+c');
+     * keyboard.hotkeyString('ctrl+shift+s');
+     * keyboard.hotkeyString('alt+f4');
+     * ```
+     */
+    hotkeyString(combo) {
+        native.keyboardHotkeyString(combo);
+    },
+    // ── Key Sequences (Macros) ──────────────────────────────────────────────
+    /**
+     * Execute a sequence of keyboard actions separated by '|'.
+     *
+     * Each action can be:
+     *   - A hotkey combo: `"ctrl+c"`
+     *   - A single key press: `"enter"`
+     *   - Literal text to type: `"type:Hello World"`
+     *
+     * @example
+     * ```typescript
+     * // Select all → Copy → Switch window → Paste
+     * keyboard.sequence('ctrl+a | ctrl+c | alt+tab | ctrl+v');
+     *
+     * // Open file dialog, type filename, press enter
+     * keyboard.sequence('ctrl+o | type:document.txt | enter');
+     *
+     * // With custom delay between actions
+     * keyboard.sequence('tab | tab | enter', { delay: 50 });
+     * ```
+     */
+    sequence(sequence, options) {
+        native.keyboardSequence(sequence, options?.delay ?? undefined);
+    },
+    // ── Key State Detection ─────────────────────────────────────────────────
+    /**
+     * Check if a key is currently held down.
+     */
+    isPressed(key) {
+        return native.keyboardIsPressed(key);
+    },
+    /**
+     * Check multiple keys at once.
+     * Returns an array of booleans matching the input keys.
+     *
+     * @example
+     * ```typescript
+     * const [ctrl, shift, alt] = keyboard.arePressed('ctrl', 'shift', 'alt');
+     * if (ctrl && !shift) { ... }
+     * ```
+     */
+    arePressed(...keys) {
+        return native.keyboardArePressed(keys);
+    },
+    /**
+     * Check if a toggle key (CapsLock, NumLock, ScrollLock) is ON.
+     *
+     * @example
+     * ```typescript
+     * if (keyboard.isToggled('capslock')) {
+     *   console.log('CapsLock is ON');
+     * }
+     * ```
+     */
+    isToggled(key) {
+        return native.keyboardIsToggled(key);
+    },
+    /**
+     * Toggle a lock key (CapsLock, NumLock, ScrollLock).
+     * Sends a press+release to flip the toggle state.
+     */
+    toggleKey(key) {
+        native.keyboardToggleKey(key);
+    },
+    // ── Key Wait Primitives ─────────────────────────────────────────────────
+    /**
+     * Wait until a specific key is pressed (blocking).
+     * Returns true if pressed, false if timed out.
+     *
+     * @example
+     * ```typescript
+     * console.log('Press Escape to continue...');
+     * keyboard.waitForKey('escape', { timeout: 10000 });
+     * ```
+     */
+    waitForKey(key, options) {
+        return native.keyboardWaitForKey(key, options?.timeout ?? undefined);
+    },
+    /**
+     * Wait until a specific key is released (blocking).
+     * Useful after `waitForKey` to detect key-up.
+     */
+    waitForKeyRelease(key, options) {
+        return native.keyboardWaitForKeyRelease(key, options?.timeout ?? undefined);
+    },
+    // ── Utilities ───────────────────────────────────────────────────────────
+    /**
+     * Get a list of all recognized key names.
+     */
+    allKeys() {
+        return native.keyboardAllKeys();
+    },
+    // ── Convenience Methods ─────────────────────────────────────────────────
+    /** Press Enter */
+    enter() {
+        native.keyboardPress('enter');
+    },
+    /** Press Tab */
+    tab() {
+        native.keyboardPress('tab');
+    },
+    /** Press Escape */
+    escape() {
+        native.keyboardPress('escape');
+    },
+    /** Press Backspace */
+    backspace(count = 1) {
+        native.keyboardTap('backspace', count, 30);
+    },
+    /** Press Delete */
+    delete(count = 1) {
+        native.keyboardTap('delete', count, 30);
+    },
+    /** Select all (Ctrl+A / Cmd+A) */
+    selectAll() {
+        native.keyboardHotkey([getModifier(), 'a']);
+    },
+    /** Copy (Ctrl+C / Cmd+C) */
+    copy() {
+        native.keyboardHotkey([getModifier(), 'c']);
+    },
+    /** Paste (Ctrl+V / Cmd+V) */
+    paste() {
+        native.keyboardHotkey([getModifier(), 'v']);
+    },
+    /** Cut (Ctrl+X / Cmd+X) */
+    cut() {
+        native.keyboardHotkey([getModifier(), 'x']);
+    },
+    /** Undo (Ctrl+Z / Cmd+Z) */
+    undo() {
+        native.keyboardHotkey([getModifier(), 'z']);
+    },
+    /** Redo (Ctrl+Shift+Z / Cmd+Shift+Z) */
+    redo() {
+        native.keyboardHotkey([getModifier(), 'shift', 'z']);
+    },
+    /** Save (Ctrl+S / Cmd+S) */
+    save() {
+        native.keyboardHotkey([getModifier(), 's']);
+    },
+    /** Find (Ctrl+F / Cmd+F) */
+    find() {
+        native.keyboardHotkey([getModifier(), 'f']);
+    },
+    /** New (Ctrl+N / Cmd+N) */
+    new() {
+        native.keyboardHotkey([getModifier(), 'n']);
+    },
+    /** Close tab/window (Ctrl+W / Cmd+W) */
+    close() {
+        native.keyboardHotkey([getModifier(), 'w']);
+    },
+    /** Print (Ctrl+P / Cmd+P) */
+    print() {
+        native.keyboardHotkey([getModifier(), 'p']);
+    },
+    /** Switch application (Alt+Tab / Cmd+Tab) */
+    switchApp() {
+        const mod = process.platform === 'darwin' ? 'cmd' : 'alt';
+        native.keyboardHotkey([mod, 'tab']);
+    },
+    // ── Async (Non-Blocking) Typing ───────────────────────────────────────
+    // Same character-by-character typing but yields to the event loop
+    // between each character so other operations can run in parallel.
+    // ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ──
+    /**
+     * Type text character-by-character — **non-blocking**.
+     *
+     * Unlike `type()` which blocks the thread, this yields to the event loop
+     * between each character. Other code (screen monitoring, mouse movement)
+     * can run in parallel while text is being typed.
+     *
+     * Returns a cancellable handle.
+     *
+     * @example
+     * ```typescript
+     * // Await completion
+     * await keyboard.typeAsync('Hello World!', { delay: 30 });
+     *
+     * // Cancel mid-type
+     * const handle = keyboard.typeAsync('Long text...');
+     * setTimeout(() => handle.cancel(), 500);
+     * await handle.promise;
+     * ```
+     */
+    typeAsync(text, options) {
+        let cancelled = false;
+        let timer = null;
+        const delay = options?.delay ?? 20;
+        const promise = new Promise((resolve) => {
+            let i = 0;
+            function nextChar() {
+                if (cancelled || i >= text.length) {
+                    resolve();
+                    return;
+                }
+                // Type one character using batch (handles Unicode properly)
+                native.keyboardTypeBatch(text[i]);
+                i++;
+                timer = setTimeout(nextChar, delay);
+            }
+            nextChar();
+        });
+        return {
+            promise,
+            cancel() {
+                cancelled = true;
+                if (timer !== null)
+                    clearTimeout(timer);
+            },
+        };
+    },
+    /**
+     * Type text with human-like random delays — **non-blocking**.
+     *
+     * Each character is typed with a random delay between minDelay and maxDelay.
+     * Non-blocking: the event loop is free between characters.
+     */
+    typeHumanizedAsync(text, options) {
+        let cancelled = false;
+        let timer = null;
+        const minDelay = options?.minDelay ?? 30;
+        const maxDelay = options?.maxDelay ?? 120;
+        const promise = new Promise((resolve) => {
+            let i = 0;
+            function nextChar() {
+                if (cancelled || i >= text.length) {
+                    resolve();
+                    return;
+                }
+                native.keyboardTypeBatch(text[i]);
+                i++;
+                const delay = minDelay + Math.random() * (maxDelay - minDelay);
+                timer = setTimeout(nextChar, delay);
+            }
+            nextChar();
+        });
+        return {
+            promise,
+            cancel() {
+                cancelled = true;
+                if (timer !== null)
+                    clearTimeout(timer);
+            },
+        };
+    },
+};
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function getModifier() {
+    return process.platform === 'darwin' ? 'cmd' : 'ctrl';
+}
+//# sourceMappingURL=keyboard.js.map

package/dist/keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.js","sourceRoot":"","sources":["../ts/keyboard.ts"],"names":[],"mappings":";AAAA,+EAA+E;AAC/E,+BAA+B;AAC/B,+EAA+E;AAC/E,8EAA8E;AAC9E,oEAAoE;AACpE,+EAA+E;;;AAI/E,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AActC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACU,QAAA,QAAQ,GAAG;IACtB,2EAA2E;IAE3E;;;OAGG;IACH,IAAI,CAAC,IAAY,EAAE,OAAqB;QACtC,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,SAAS,CAAC,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,IAAY,EAAE,OAA8B;QACxD,MAAM,CAAC,qBAAqB,CAC1B,IAAI,EACJ,OAAO,EAAE,QAAQ,IAAI,SAAS,EAC9B,OAAO,EAAE,QAAQ,IAAI,SAAS,CAC/B,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,IAAY;QACpB,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACH,iBAAiB,CAAC,IAAY,EAAE,GAAG,SAAmB;QACpD,MAAM,CAAC,yBAAyB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACpD,CAAC;IAED,2EAA2E;IAE3E;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,GAAW;QACf,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,GAAW;QACd,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,EAAE,CAAC,GAAW;QACZ,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,GAAW,EAAE,KAAc,EAAE,KAAc;QAC7C,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,2EAA2E;IAE3E;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,IAAc;QACtB,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;OAUG;IACH,YAAY,CAAC,KAAa;QACxB,MAAM,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,2EAA2E;IAE3E;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,QAAgB,EAAE,OAA4B;QACrD,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,IAAI,SAAS,CAAC,CAAC;IACjE,CAAC;IAED,2EAA2E;IAE3E;;OAEG;IACH,SAAS,CAAC,GAAW;QACnB,OAAO,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;;;OASG;IACH,UAAU,CAAC,GAAG,IAAc;QAC1B,OAAO,MAAM,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;;OASG;IACH,SAAS,CAAC,GAAW;QACnB,OAAO,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,GAAW;QACnB,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,2EAA2E;IAE3E;;;;;;;;;OASG;IACH,UAAU,CAAC,GAAW,EAAE,OAA2B;QACjD,OAAO,MAAM,CAAC,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,IAAI,SAAS,CAAC,CAAC;IACvE,CAAC;IAED;;;OAGG;IACH,iBAAiB,CAAC,GAAW,EAAE,OAA2B;QACxD,OAAO,MAAM,CAAC,yBAAyB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,IAAI,SAAS,CAAC,CAAC;IAC9E,CAAC;IAED,2EAA2E;IAE3E;;OAEG;IACH,OAAO;QACL,OAAO,MAAM,CAAC,eAAe,EAAE,CAAC;IAClC,CAAC;IAED,2EAA2E;IAE3E,kBAAkB;IAClB,KAAK;QACH,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,gBAAgB;IAChB,GAAG;QACD,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,mBAAmB;IACnB,MAAM;QACJ,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,sBAAsB;IACtB,SAAS,CAAC,QAAgB,CAAC;QACzB,MAAM,CAAC,WAAW,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,mBAAmB;IACnB,MAAM,CAAC,QAAgB,CAAC;QACtB,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,kCAAkC;IAClC,SAAS;QACP,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,4BAA4B;IAC5B,IAAI;QACF,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,6BAA6B;IAC7B,KAAK;QACH,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,2BAA2B;IAC3B,GAAG;QACD,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,4BAA4B;IAC5B,IAAI;QACF,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,wCAAwC;IACxC,IAAI;QACF,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,4BAA4B;IAC5B,IAAI;QACF,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,4BAA4B;IAC5B,IAAI;QACF,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,2BAA2B;IAC3B,GAAG;QACD,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,wCAAwC;IACxC,KAAK;QACH,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,6BAA6B;IAC7B,KAAK;QACH,MAAM,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,6CAA6C;IAC7C,SAAS;QACP,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;QAC1D,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,yEAAyE;IACzE,kEAAkE;IAClE,kEAAkE;IAClE,uEAAuE;IAEvE;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CACP,IAAY,EACZ,OAA4B;QAE5B,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,IAAI,KAAK,GAAyC,IAAI,CAAC;QACvD,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;QAEnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5C,IAAI,CAAC,GAAG,CAAC,CAAC;YACV,SAAS,QAAQ;gBACf,IAAI,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;oBAClC,OAAO,EAAE,CAAC;oBACV,OAAO;gBACT,CAAC;gBACD,4DAA4D;gBAC5D,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBAClC,CAAC,EAAE,CAAC;gBACJ,KAAK,GAAG,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACtC,CAAC;YACD,QAAQ,EAAE,CAAC;QACb,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,OAAO;YACP,MAAM;gBACJ,SAAS,GAAG,IAAI,CAAC;gBACjB,IAAI,KAAK,KAAK,IAAI;oBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC1C,CAAC;SACF,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAChB,IAAY,EACZ,OAAkD;QAElD,IAAI,SAAS,GAAG,KAAK,CAAC;QACtB,IAAI,KAAK,GAAyC,IAAI,CAAC;QACvD,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,GAAG,CAAC;QAE1C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5C,IAAI,CAAC,GAAG,CAAC,CAAC;YACV,SAAS,QAAQ;gBACf,IAAI,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;oBAClC,OAAO,EAAE,CAAC;oBACV,OAAO;gBACT,CAAC;gBACD,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBAClC,CAAC,EAAE,CAAC;gBACJ,MAAM,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC;gBAC/D,KAAK,GAAG,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACtC,CAAC;YACD,QAAQ,EAAE,CAAC;QACb,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,OAAO;YACP,MAAM;gBACJ,SAAS,GAAG,IAAI,CAAC;gBACjB,IAAI,KAAK,KAAK,IAAI;oBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC1C,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF,+EAA+E;AAE/E,SAAS,WAAW;IAClB,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC"}