@humanjs/playwright 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,8 +1,81 @@
-import { ReadKind, PersonalityConfig, HumanPlugin, Point, Personality } from '@humanjs/core';
+import { Point, ReadKind, PersonalityConfig, HumanPlugin, Personality } from '@humanjs/core';
 export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions, DwellProfile, HumanAction, HumanPlugin, HumanizePathOptions, Keystroke, KnownActionType, MouseProfile, Personality, PersonalityConfig, PersonalityExtension, PlanTypingOptions, PluginContext, Point, PresetName, ReadKind, ReadingProfile, Rng, ScrollProfile, ScrollSegment, TypingProfile, applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, computeReadingDwellMs, countWords, createRng, distracted, fast, humanizePath, planScroll, planTypeKeystrokes, precise, resolvePersonality, sleep } from '@humanjs/core';
 import { Locator, BrowserContext, Page } from 'playwright';
 export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } from 'playwright';
 
+/**
+ * Modifier tokens accepted in a `human.press()` chord. `Mod` and `CmdOrCtrl` /
+ * `CommandOrControl` are the magic auto-mapping tokens (Meta on Mac,
+ * Control elsewhere). The rest are literal — they always resolve to the
+ * keycode they name, on every platform.
+ *
+ * Canonical-case names are listed here for IntelliSense; the runtime
+ * parser is case-insensitive, so `'cmd+s'` and `'CMD+S'` work too — they
+ * just won't autocomplete.
+ */
+type KeyModifier = 'Mod' | 'CmdOrCtrl' | 'CommandOrControl' | 'Cmd' | 'Command' | 'Meta' | 'Win' | 'Super' | 'Ctrl' | 'Control' | 'Alt' | 'Option' | 'Opt' | 'Shift';
+/**
+ * The canonical key names that autocomplete in a `KeyOrChord`. Mirrors
+ * Playwright's accepted key vocabulary, plus a few common synonyms.
+ * CamelCase names (`ArrowDown`, `PageUp`) are listed in their canonical
+ * form — `normalizeKey` preserves case from the input, so what you type is
+ * what gets dispatched.
+ *
+ * Not exhaustive: every other Playwright key (less-common Numpad keys,
+ * `BracketLeft`, locale-specific keys, etc.) is outside the typed union
+ * and needs a cast at the call site (`'BracketLeft' as KeyOrChord`). The
+ * runtime parser handles them — the type just doesn't enumerate them,
+ * because adding a `(string & {})` escape hatch would collapse TypeScript's
+ * template-literal IntelliSense for the chord autocompletes.
+ */
+type KeyName = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'PageUp' | 'PageDown' | 'Home' | 'End' | 'Enter' | 'Tab' | 'Escape' | 'Space' | 'Backspace' | 'Delete' | 'Insert' | 'CapsLock' | 'NumLock' | 'ScrollLock' | 'PrintScreen' | 'Pause';
+/**
+ * Strings accepted by `human.press(key)`:
+ *
+ *  - A bare known key: `'Enter'`, `'F4'`, `'ArrowDown'`, `'S'`, …
+ *  - One known modifier + a known key: `'Mod+S'`, `'Shift+ArrowDown'`, …
+ *  - Two known modifiers + a known key: `'Mod+Shift+P'`, `'Ctrl+Alt+Tab'`, …
+ *
+ * Every member of the union is a fully-enumerated literal, which is what
+ * makes IDE autocomplete work — type `'Shift+'` and you get every
+ * `Shift+<key>` combination as a completion. Adding a `(string & {})`
+ * escape hatch anywhere would collapse that down to a single wide
+ * template member, killing the completion list.
+ *
+ * Modifier typos (`'Mosd+S'`) and uncommon-key typos (`'Mod+BraketLeft'`)
+ * are both TS errors at the call site — the closed sets on both sides
+ * give you compile-time protection that Playwright's plain `string` key
+ * type can't.
+ *
+ * **Escape hatch for uncommon keys.** Less-common Playwright keys
+ * (`'BracketLeft'`, `'NumpadAdd'`, locale-specific keys, …) and 3+
+ * modifier chords (`'Ctrl+Shift+Alt+K'`) aren't in the union and need a
+ * cast at the call site:
+ *
+ * ```ts
+ * await human.press('Mod+BracketLeft' as KeyOrChord);
+ * await human.press('Ctrl+Shift+Alt+K' as KeyOrChord);
+ * ```
+ *
+ * The runtime parser handles these fine — the cast just acknowledges
+ * "I'm using a key outside the autocomplete vocabulary." If you find
+ * yourself casting often for a specific key, propose adding it to
+ * `KeyName` in a PR.
+ *
+ * Lowercase modifiers (`'mod+s'`) also don't typecheck even though the
+ * runtime accepts them — TS-strict steers users toward the canonical
+ * casing, which keeps key strings consistent across a codebase.
+ */
+type KeyOrChord = KeyName | `${KeyModifier}+${KeyName}` | `${KeyModifier}+${KeyModifier}+${KeyName}`;
+/** Result of a `press` action. */
+interface PressResult {
+    /** The exact chord that was dispatched (after Mod-resolution). */
+    readonly dispatched: string;
+}
+
+/** Anything that can resolve to a click/move point. */
+type MouseTarget = Locator | string | Point;
+
 /**
  * What to read:
  *  - `string`: a Playwright-compatible selector (matches `click()` / `type()`).
@@ -393,6 +466,53 @@ interface Human {
      * native `locator.click()` is used directly.
      */
     click(target: Locator | string): Promise<void>;
+    /**
+     * Right-click `target` — opens a native context menu. Same Bezier-path
+     * motion and hover dwell as `click()`; only the dispatched button differs.
+     *
+     * In `speed: 'instant'`, falls back to `locator.click({ button: 'right' })`.
+     */
+    rightClick(target: Locator | string): Promise<void>;
+    /**
+     * Move the cursor to `target` along a humanized Bezier path and settle
+     * on it — no click is dispatched. Useful for hover-triggered UI
+     * (tooltips, dropdowns), for positioning the cursor before a non-target
+     * action, or for visible demos where the cursor should pause on
+     * something noteworthy.
+     *
+     * In `speed: 'instant'`, dispatches one `mouse.move()` to the element's
+     * center.
+     */
+    hover(target: Locator | string): Promise<void>;
+    /**
+     * Move the cursor to `target` along a humanized Bezier path. Pure
+     * positioning — no settle dwell, no element interaction. `target` accepts
+     * a CSS selector, a `Locator`, or a literal `Point`; the `Point` form
+     * lets you position the cursor anywhere (canvas, SVG, dead space) without
+     * a DOM element to anchor on.
+     *
+     * Distinct from `hover()`: `hover` is element-bound and includes a settle
+     * dwell to let hover-state UI fire (tooltips, dropdowns). `move` is
+     * positional only — use it when you want the cursor placed somewhere
+     * without implying interaction with what's under it (pre-press
+     * placement, canvas painting, cinematic beats).
+     *
+     * In `speed: 'instant'`, dispatches one `mouse.move()` at the resolved
+     * coordinates.
+     */
+    move(target: MouseTarget): Promise<void>;
+    /**
+     * Drag from `from` to `to`. Each endpoint accepts a CSS selector, a
+     * `Locator`, or a literal `Point` — the last form matters for canvas /
+     * SVG / slider drags where the destination isn't a DOM element.
+     *
+     * The motion is two humanized paths back-to-back: cursor → source,
+     * then source → destination with the left button held throughout.
+     *
+     * In `speed: 'instant'`, dispatches `mouse.down → move → up` at the
+     * resolved coordinates without humanized motion.
+     */
+    drag(from: MouseTarget, to: MouseTarget): Promise<void>;
     /**
      * Type `value` into `target` with humanized per-key timing, optional typo
      * injection (with backspace recovery), and occasional think-pauses.
@@ -404,6 +524,48 @@ interface Human {
      * zero inter-key delay — events still fire, but humanization is skipped.
      */
     type(target: Locator | string, value: string): Promise<void>;
+    /**
+     * Insert `value` into `target` in one shot — the Cmd-V semantic. No
+     * per-character timing. Like `type()`, drives an implicit click to focus
+     * the field first; unlike `type()`, dispatches the whole value via
+     * `keyboard.insertText` rather than per-key presses.
+     *
+     * Use this for long strings (code blocks, multi-line content, secrets)
+     * where the typing simulation would be slow and unnecessary. If you need
+     * the page's `paste` event handler to fire, call `human.press('Mod+V')`
+     * after setting clipboard contents yourself.
+     *
+     * In `speed: 'instant'`, behaves identically — paste is already instant
+     * by nature.
+     */
+    paste(target: Locator | string, value: string): Promise<void>;
+    /**
+     * Press a single key (`'Tab'`, `'Enter'`, `'Escape'`, `'ArrowDown'`, …)
+     * or a keyboard chord (`'Mod+S'`, `'Cmd+Shift+P'`, `'Ctrl+C'`, …).
+     *
+     * Modifier rules:
+     *
+     * - `Mod` / `CmdOrCtrl` / `CommandOrControl` — magic: `Meta` on Mac,
+     *   `Control` elsewhere. Use for cross-platform app shortcuts. The three
+     *   are aliases; `Mod` is shortest.
+     * - `Cmd`, `Command`, `Meta`, `Win`, `Super` — literal `Meta` keycode
+     *   (Command on Mac, Windows key on Windows, Super on Linux).
+     * - `Ctrl`, `Control` — literal Control. Stays Control on every OS.
+     * - `Alt`, `Option`, `Opt` — literal Alt.
+     * - `Shift` — literal Shift.
+     *
+     * Case-insensitive. Throws on unknown modifiers. The `KeyOrChord` type
+     * is a template-literal union of every modifier × key combination (up to
+     * two literal modifiers + a key), so IDEs autocomplete common bare keys
+     * and chords as you type. Less common keys (`BracketLeft`, `NumpadAdd`,
+     * locale-specific keys) still typecheck through the union's string
+     * escape hatch — they just don't autocomplete.
+     *
+     * Does **not** move the cursor — keyboard input dispatches against
+     * focus, not cursor position. Compose with `click` / `hover` / `move`
+     * when you need both.
+     */
+    press(key: KeyOrChord): Promise<void>;
     /**
      * Dwell as if reading `target` — the third pillar of humanization after
      * the cursor and the keyboard. Real users pause to read; HumanJS models
@@ -545,4 +707,4 @@ interface HumanRecordOptions {
  */
 declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
 
-export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };
+export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PressResult, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };

package/dist/index.d.ts

@@ -1,8 +1,81 @@
-import { ReadKind, PersonalityConfig, HumanPlugin, Point, Personality } from '@humanjs/core';
+import { Point, ReadKind, PersonalityConfig, HumanPlugin, Personality } from '@humanjs/core';
 export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions, DwellProfile, HumanAction, HumanPlugin, HumanizePathOptions, Keystroke, KnownActionType, MouseProfile, Personality, PersonalityConfig, PersonalityExtension, PlanTypingOptions, PluginContext, Point, PresetName, ReadKind, ReadingProfile, Rng, ScrollProfile, ScrollSegment, TypingProfile, applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, computeReadingDwellMs, countWords, createRng, distracted, fast, humanizePath, planScroll, planTypeKeystrokes, precise, resolvePersonality, sleep } from '@humanjs/core';
 import { Locator, BrowserContext, Page } from 'playwright';
 export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } from 'playwright';
 
+/**
+ * Modifier tokens accepted in a `human.press()` chord. `Mod` and `CmdOrCtrl` /
+ * `CommandOrControl` are the magic auto-mapping tokens (Meta on Mac,
+ * Control elsewhere). The rest are literal — they always resolve to the
+ * keycode they name, on every platform.
+ *
+ * Canonical-case names are listed here for IntelliSense; the runtime
+ * parser is case-insensitive, so `'cmd+s'` and `'CMD+S'` work too — they
+ * just won't autocomplete.
+ */
+type KeyModifier = 'Mod' | 'CmdOrCtrl' | 'CommandOrControl' | 'Cmd' | 'Command' | 'Meta' | 'Win' | 'Super' | 'Ctrl' | 'Control' | 'Alt' | 'Option' | 'Opt' | 'Shift';
+/**
+ * The canonical key names that autocomplete in a `KeyOrChord`. Mirrors
+ * Playwright's accepted key vocabulary, plus a few common synonyms.
+ * CamelCase names (`ArrowDown`, `PageUp`) are listed in their canonical
+ * form — `normalizeKey` preserves case from the input, so what you type is
+ * what gets dispatched.
+ *
+ * Not exhaustive: every other Playwright key (less-common Numpad keys,
+ * `BracketLeft`, locale-specific keys, etc.) is outside the typed union
+ * and needs a cast at the call site (`'BracketLeft' as KeyOrChord`). The
+ * runtime parser handles them — the type just doesn't enumerate them,
+ * because adding a `(string & {})` escape hatch would collapse TypeScript's
+ * template-literal IntelliSense for the chord autocompletes.
+ */
+type KeyName = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'PageUp' | 'PageDown' | 'Home' | 'End' | 'Enter' | 'Tab' | 'Escape' | 'Space' | 'Backspace' | 'Delete' | 'Insert' | 'CapsLock' | 'NumLock' | 'ScrollLock' | 'PrintScreen' | 'Pause';
+/**
+ * Strings accepted by `human.press(key)`:
+ *
+ *  - A bare known key: `'Enter'`, `'F4'`, `'ArrowDown'`, `'S'`, …
+ *  - One known modifier + a known key: `'Mod+S'`, `'Shift+ArrowDown'`, …
+ *  - Two known modifiers + a known key: `'Mod+Shift+P'`, `'Ctrl+Alt+Tab'`, …
+ *
+ * Every member of the union is a fully-enumerated literal, which is what
+ * makes IDE autocomplete work — type `'Shift+'` and you get every
+ * `Shift+<key>` combination as a completion. Adding a `(string & {})`
+ * escape hatch anywhere would collapse that down to a single wide
+ * template member, killing the completion list.
+ *
+ * Modifier typos (`'Mosd+S'`) and uncommon-key typos (`'Mod+BraketLeft'`)
+ * are both TS errors at the call site — the closed sets on both sides
+ * give you compile-time protection that Playwright's plain `string` key
+ * type can't.
+ *
+ * **Escape hatch for uncommon keys.** Less-common Playwright keys
+ * (`'BracketLeft'`, `'NumpadAdd'`, locale-specific keys, …) and 3+
+ * modifier chords (`'Ctrl+Shift+Alt+K'`) aren't in the union and need a
+ * cast at the call site:
+ *
+ * ```ts
+ * await human.press('Mod+BracketLeft' as KeyOrChord);
+ * await human.press('Ctrl+Shift+Alt+K' as KeyOrChord);
+ * ```
+ *
+ * The runtime parser handles these fine — the cast just acknowledges
+ * "I'm using a key outside the autocomplete vocabulary." If you find
+ * yourself casting often for a specific key, propose adding it to
+ * `KeyName` in a PR.
+ *
+ * Lowercase modifiers (`'mod+s'`) also don't typecheck even though the
+ * runtime accepts them — TS-strict steers users toward the canonical
+ * casing, which keeps key strings consistent across a codebase.
+ */
+type KeyOrChord = KeyName | `${KeyModifier}+${KeyName}` | `${KeyModifier}+${KeyModifier}+${KeyName}`;
+/** Result of a `press` action. */
+interface PressResult {
+    /** The exact chord that was dispatched (after Mod-resolution). */
+    readonly dispatched: string;
+}
+
+/** Anything that can resolve to a click/move point. */
+type MouseTarget = Locator | string | Point;
+
 /**
  * What to read:
  *  - `string`: a Playwright-compatible selector (matches `click()` / `type()`).
@@ -393,6 +466,53 @@ interface Human {
      * native `locator.click()` is used directly.
      */
     click(target: Locator | string): Promise<void>;
+    /**
+     * Right-click `target` — opens a native context menu. Same Bezier-path
+     * motion and hover dwell as `click()`; only the dispatched button differs.
+     *
+     * In `speed: 'instant'`, falls back to `locator.click({ button: 'right' })`.
+     */
+    rightClick(target: Locator | string): Promise<void>;
+    /**
+     * Move the cursor to `target` along a humanized Bezier path and settle
+     * on it — no click is dispatched. Useful for hover-triggered UI
+     * (tooltips, dropdowns), for positioning the cursor before a non-target
+     * action, or for visible demos where the cursor should pause on
+     * something noteworthy.
+     *
+     * In `speed: 'instant'`, dispatches one `mouse.move()` to the element's
+     * center.
+     */
+    hover(target: Locator | string): Promise<void>;
+    /**
+     * Move the cursor to `target` along a humanized Bezier path. Pure
+     * positioning — no settle dwell, no element interaction. `target` accepts
+     * a CSS selector, a `Locator`, or a literal `Point`; the `Point` form
+     * lets you position the cursor anywhere (canvas, SVG, dead space) without
+     * a DOM element to anchor on.
+     *
+     * Distinct from `hover()`: `hover` is element-bound and includes a settle
+     * dwell to let hover-state UI fire (tooltips, dropdowns). `move` is
+     * positional only — use it when you want the cursor placed somewhere
+     * without implying interaction with what's under it (pre-press
+     * placement, canvas painting, cinematic beats).
+     *
+     * In `speed: 'instant'`, dispatches one `mouse.move()` at the resolved
+     * coordinates.
+     */
+    move(target: MouseTarget): Promise<void>;
+    /**
+     * Drag from `from` to `to`. Each endpoint accepts a CSS selector, a
+     * `Locator`, or a literal `Point` — the last form matters for canvas /
+     * SVG / slider drags where the destination isn't a DOM element.
+     *
+     * The motion is two humanized paths back-to-back: cursor → source,
+     * then source → destination with the left button held throughout.
+     *
+     * In `speed: 'instant'`, dispatches `mouse.down → move → up` at the
+     * resolved coordinates without humanized motion.
+     */
+    drag(from: MouseTarget, to: MouseTarget): Promise<void>;
     /**
      * Type `value` into `target` with humanized per-key timing, optional typo
      * injection (with backspace recovery), and occasional think-pauses.
@@ -404,6 +524,48 @@ interface Human {
      * zero inter-key delay — events still fire, but humanization is skipped.
      */
     type(target: Locator | string, value: string): Promise<void>;
+    /**
+     * Insert `value` into `target` in one shot — the Cmd-V semantic. No
+     * per-character timing. Like `type()`, drives an implicit click to focus
+     * the field first; unlike `type()`, dispatches the whole value via
+     * `keyboard.insertText` rather than per-key presses.
+     *
+     * Use this for long strings (code blocks, multi-line content, secrets)
+     * where the typing simulation would be slow and unnecessary. If you need
+     * the page's `paste` event handler to fire, call `human.press('Mod+V')`
+     * after setting clipboard contents yourself.
+     *
+     * In `speed: 'instant'`, behaves identically — paste is already instant
+     * by nature.
+     */
+    paste(target: Locator | string, value: string): Promise<void>;
+    /**
+     * Press a single key (`'Tab'`, `'Enter'`, `'Escape'`, `'ArrowDown'`, …)
+     * or a keyboard chord (`'Mod+S'`, `'Cmd+Shift+P'`, `'Ctrl+C'`, …).
+     *
+     * Modifier rules:
+     *
+     * - `Mod` / `CmdOrCtrl` / `CommandOrControl` — magic: `Meta` on Mac,
+     *   `Control` elsewhere. Use for cross-platform app shortcuts. The three
+     *   are aliases; `Mod` is shortest.
+     * - `Cmd`, `Command`, `Meta`, `Win`, `Super` — literal `Meta` keycode
+     *   (Command on Mac, Windows key on Windows, Super on Linux).
+     * - `Ctrl`, `Control` — literal Control. Stays Control on every OS.
+     * - `Alt`, `Option`, `Opt` — literal Alt.
+     * - `Shift` — literal Shift.
+     *
+     * Case-insensitive. Throws on unknown modifiers. The `KeyOrChord` type
+     * is a template-literal union of every modifier × key combination (up to
+     * two literal modifiers + a key), so IDEs autocomplete common bare keys
+     * and chords as you type. Less common keys (`BracketLeft`, `NumpadAdd`,
+     * locale-specific keys) still typecheck through the union's string
+     * escape hatch — they just don't autocomplete.
+     *
+     * Does **not** move the cursor — keyboard input dispatches against
+     * focus, not cursor position. Compose with `click` / `hover` / `move`
+     * when you need both.
+     */
+    press(key: KeyOrChord): Promise<void>;
     /**
      * Dwell as if reading `target` — the third pillar of humanization after
      * the cursor and the keyboard. Real users pause to read; HumanJS models
@@ -545,4 +707,4 @@ interface HumanRecordOptions {
  */
 declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
 
-export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };
+export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PressResult, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };