@humanjs/playwright 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -3,6 +3,14 @@ export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions
 import { Locator, BrowserContext, Page } from 'playwright';
 export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } from 'playwright';
 
+/** Anything that can resolve to a click/move point. */
+type MouseTarget = Locator | string | Point;
+
+/** Values accepted by {@link executeSelectOption} — the Playwright `selectOption` shape. */
+type SelectOptionValues = Parameters<Locator['selectOption']>[0];
+/** Files accepted by {@link executeUpload} — the Playwright `setInputFiles` shape. */
+type UploadFiles = Parameters<Locator['setInputFiles']>[0];
+
 /**
  * Modifier tokens accepted in a `human.press()` chord. `Mod` and `CmdOrCtrl` /
  * `CommandOrControl` are the magic auto-mapping tokens (Meta on Mac,
@@ -73,9 +81,6 @@ interface PressResult {
     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()`).
@@ -536,6 +541,17 @@ interface Human {
      * `mouse.click({ button: 'right' })` at the coordinates.
      */
     rightClick(target: MouseTarget): Promise<void>;
+    /**
+     * Double-click `target`. Identical humanized approach to `click()` — same
+     * Bezier path, hover dwell, and occasional near-miss — but the final
+     * dispatch is a double-click (two presses within the OS double-click
+     * window). Accepts the same selector / `Locator` / `Point` targets.
+     *
+     * In `speed: 'instant'`, element targets fall back to
+     * `locator.click({ clickCount: 2 })`; a `Point` dispatches
+     * `mouse.click(x, y, { clickCount: 2 })`.
+     */
+    doubleClick(target: MouseTarget): 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
@@ -602,6 +618,70 @@ interface Human {
      * by nature.
      */
     paste(target: Locator | string, value: string): Promise<void>;
+    /**
+     * Clear a text field `target` (input, textarea, or contenteditable) with a
+     * humanized gesture: click to focus, **select-all**, a beat, then **delete**
+     * — the real keyboard motion a person uses to wipe a field before retyping,
+     * not a silent value reset. Fires the keydown/up + `input` events the page
+     * expects.
+     *
+     * Pair with `type()` to edit an existing value:
+     * `await human.clear('#name'); await human.type('#name', 'New');`
+     *
+     * In `speed: 'instant'`, delegates to Playwright's native `locator.clear()`.
+     */
+    clear(target: Locator | string): Promise<void>;
+    /**
+     * Tick a checkbox or radio `target`. Moves the cursor to the control and
+     * clicks it with the same humanized motion as `click()` — but only when
+     * needed: if it already reports checked, no click fires (a real user
+     * doesn't re-click a box that's already ticked). The resulting state is
+     * verified; trying to `check` something that won't toggle throws.
+     *
+     * `target` is element-bound (selector or `Locator`). In `speed: 'instant'`,
+     * delegates to Playwright's native `locator.check()`.
+     */
+    check(target: Locator | string): Promise<void>;
+    /**
+     * Untick a checkbox `target`. Mirror of `check()` — humanized click only if
+     * currently checked, with state verification afterward. Radios can't be
+     * unchecked by clicking (select a different option instead); attempting it
+     * throws a clear error.
+     *
+     * In `speed: 'instant'`, delegates to `locator.uncheck()`.
+     */
+    uncheck(target: Locator | string): Promise<void>;
+    /**
+     * Choose option(s) in a native `<select>` `target`. The cursor moves to the
+     * dropdown and settles on it (humanized), then the value is set — native
+     * selects open an OS menu automation can't drive visually, so the *approach*
+     * is humanized while the choice itself is set programmatically (firing
+     * `input`/`change`), exactly as Playwright does. For custom DOM dropdowns,
+     * drive the rendered options with `click` instead.
+     *
+     * `values` takes the Playwright `selectOption` shape — a value string, an
+     * array of values, or `{ value | label | index }`. Returns the option
+     * values that ended up selected.
+     *
+     * In `speed: 'instant'`, sets the value with no cursor motion.
+     */
+    selectOption(target: Locator | string, values: SelectOptionValues): Promise<string[]>;
+    /**
+     * Attach file(s) to a file-input `target`. The cursor moves to the control
+     * (visible in recordings / the overlay), then the files are attached via
+     * `setInputFiles`. Unlike a real click this never opens the OS file dialog
+     * (which would hang) — files are set directly, the way Playwright models
+     * uploads.
+     *
+     * `target` should be the `<input type="file">`. For the common hidden-input-
+     * behind-a-styled-button pattern there's no visible control to approach, so
+     * the motion is skipped and the files are attached directly. `files` takes
+     * the Playwright `setInputFiles` shape (a path, an array of paths, or
+     * in-memory `{ name, mimeType, buffer }` payloads).
+     *
+     * In `speed: 'instant'`, attaches the files with no cursor motion.
+     */
+    upload(target: Locator | string, files: UploadFiles): Promise<void>;
     /**
      * Press a single key (`'Tab'`, `'Enter'`, `'Escape'`, `'ArrowDown'`, …)
      * or a keyboard chord (`'Mod+S'`, `'Cmd+Shift+P'`, `'Ctrl+C'`, …).
@@ -759,6 +839,22 @@ interface Human {
      * Not a humanized action: no plugin events fire.
      */
     content(): Promise<string>;
+    /**
+     * Accessibility-tree **outline** of the page (or a region) — every
+     * interactive element and landmark by its ARIA role + accessible name,
+     * rendered as compact YAML (Playwright's `ariaSnapshot`). The most
+     * token-efficient way for an AI agent to see what's actionable and pick a
+     * selector: the names map directly to `getByRole` / accessible-name
+     * selectors, which HumanJS already favors.
+     *
+     * Prefer this over {@link Human.content} when the question is "what can I
+     * click / fill"; reach for {@link Human.screenshot} when you need the
+     * visual layout. Pass `target` to scope the outline to a region.
+     *
+     * Not a humanized action: no plugin events fire. Requires Playwright ≥ 1.49
+     * (when `ariaSnapshot` landed).
+     */
+    outline(target?: Locator | string): Promise<string>;
     /**
      * Current URL of the page. Forwards to `page.url()`. Synchronous return
      * because Playwright's underlying API is sync.
@@ -886,4 +982,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 KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PlaywrightTestOptions, 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 };
+export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PlaywrightTestOptions, type PressResult, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type SelectOptionValues, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, type UploadFiles, createHuman, installMouseHelper };

package/dist/index.d.ts

@@ -3,6 +3,14 @@ export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions
 import { Locator, BrowserContext, Page } from 'playwright';
 export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } from 'playwright';
 
+/** Anything that can resolve to a click/move point. */
+type MouseTarget = Locator | string | Point;
+
+/** Values accepted by {@link executeSelectOption} — the Playwright `selectOption` shape. */
+type SelectOptionValues = Parameters<Locator['selectOption']>[0];
+/** Files accepted by {@link executeUpload} — the Playwright `setInputFiles` shape. */
+type UploadFiles = Parameters<Locator['setInputFiles']>[0];
+
 /**
  * Modifier tokens accepted in a `human.press()` chord. `Mod` and `CmdOrCtrl` /
  * `CommandOrControl` are the magic auto-mapping tokens (Meta on Mac,
@@ -73,9 +81,6 @@ interface PressResult {
     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()`).
@@ -536,6 +541,17 @@ interface Human {
      * `mouse.click({ button: 'right' })` at the coordinates.
      */
     rightClick(target: MouseTarget): Promise<void>;
+    /**
+     * Double-click `target`. Identical humanized approach to `click()` — same
+     * Bezier path, hover dwell, and occasional near-miss — but the final
+     * dispatch is a double-click (two presses within the OS double-click
+     * window). Accepts the same selector / `Locator` / `Point` targets.
+     *
+     * In `speed: 'instant'`, element targets fall back to
+     * `locator.click({ clickCount: 2 })`; a `Point` dispatches
+     * `mouse.click(x, y, { clickCount: 2 })`.
+     */
+    doubleClick(target: MouseTarget): 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
@@ -602,6 +618,70 @@ interface Human {
      * by nature.
      */
     paste(target: Locator | string, value: string): Promise<void>;
+    /**
+     * Clear a text field `target` (input, textarea, or contenteditable) with a
+     * humanized gesture: click to focus, **select-all**, a beat, then **delete**
+     * — the real keyboard motion a person uses to wipe a field before retyping,
+     * not a silent value reset. Fires the keydown/up + `input` events the page
+     * expects.
+     *
+     * Pair with `type()` to edit an existing value:
+     * `await human.clear('#name'); await human.type('#name', 'New');`
+     *
+     * In `speed: 'instant'`, delegates to Playwright's native `locator.clear()`.
+     */
+    clear(target: Locator | string): Promise<void>;
+    /**
+     * Tick a checkbox or radio `target`. Moves the cursor to the control and
+     * clicks it with the same humanized motion as `click()` — but only when
+     * needed: if it already reports checked, no click fires (a real user
+     * doesn't re-click a box that's already ticked). The resulting state is
+     * verified; trying to `check` something that won't toggle throws.
+     *
+     * `target` is element-bound (selector or `Locator`). In `speed: 'instant'`,
+     * delegates to Playwright's native `locator.check()`.
+     */
+    check(target: Locator | string): Promise<void>;
+    /**
+     * Untick a checkbox `target`. Mirror of `check()` — humanized click only if
+     * currently checked, with state verification afterward. Radios can't be
+     * unchecked by clicking (select a different option instead); attempting it
+     * throws a clear error.
+     *
+     * In `speed: 'instant'`, delegates to `locator.uncheck()`.
+     */
+    uncheck(target: Locator | string): Promise<void>;
+    /**
+     * Choose option(s) in a native `<select>` `target`. The cursor moves to the
+     * dropdown and settles on it (humanized), then the value is set — native
+     * selects open an OS menu automation can't drive visually, so the *approach*
+     * is humanized while the choice itself is set programmatically (firing
+     * `input`/`change`), exactly as Playwright does. For custom DOM dropdowns,
+     * drive the rendered options with `click` instead.
+     *
+     * `values` takes the Playwright `selectOption` shape — a value string, an
+     * array of values, or `{ value | label | index }`. Returns the option
+     * values that ended up selected.
+     *
+     * In `speed: 'instant'`, sets the value with no cursor motion.
+     */
+    selectOption(target: Locator | string, values: SelectOptionValues): Promise<string[]>;
+    /**
+     * Attach file(s) to a file-input `target`. The cursor moves to the control
+     * (visible in recordings / the overlay), then the files are attached via
+     * `setInputFiles`. Unlike a real click this never opens the OS file dialog
+     * (which would hang) — files are set directly, the way Playwright models
+     * uploads.
+     *
+     * `target` should be the `<input type="file">`. For the common hidden-input-
+     * behind-a-styled-button pattern there's no visible control to approach, so
+     * the motion is skipped and the files are attached directly. `files` takes
+     * the Playwright `setInputFiles` shape (a path, an array of paths, or
+     * in-memory `{ name, mimeType, buffer }` payloads).
+     *
+     * In `speed: 'instant'`, attaches the files with no cursor motion.
+     */
+    upload(target: Locator | string, files: UploadFiles): Promise<void>;
     /**
      * Press a single key (`'Tab'`, `'Enter'`, `'Escape'`, `'ArrowDown'`, …)
      * or a keyboard chord (`'Mod+S'`, `'Cmd+Shift+P'`, `'Ctrl+C'`, …).
@@ -759,6 +839,22 @@ interface Human {
      * Not a humanized action: no plugin events fire.
      */
     content(): Promise<string>;
+    /**
+     * Accessibility-tree **outline** of the page (or a region) — every
+     * interactive element and landmark by its ARIA role + accessible name,
+     * rendered as compact YAML (Playwright's `ariaSnapshot`). The most
+     * token-efficient way for an AI agent to see what's actionable and pick a
+     * selector: the names map directly to `getByRole` / accessible-name
+     * selectors, which HumanJS already favors.
+     *
+     * Prefer this over {@link Human.content} when the question is "what can I
+     * click / fill"; reach for {@link Human.screenshot} when you need the
+     * visual layout. Pass `target` to scope the outline to a region.
+     *
+     * Not a humanized action: no plugin events fire. Requires Playwright ≥ 1.49
+     * (when `ariaSnapshot` landed).
+     */
+    outline(target?: Locator | string): Promise<string>;
     /**
      * Current URL of the page. Forwards to `page.url()`. Synchronous return
      * because Playwright's underlying API is sync.
@@ -886,4 +982,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 KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PlaywrightTestOptions, 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 };
+export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type KeyModifier, type KeyName, type KeyOrChord, type MouseTarget, type PlaywrightTestOptions, type PressResult, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type SelectOptionValues, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, type UploadFiles, createHuman, installMouseHelper };