@humanjs/playwright 0.4.0 → 0.6.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()`).
@@ -385,14 +458,69 @@ interface Human {
     /**
      * Move the mouse along a humanized Bezier path to `target` and click.
      *
-     * `target` accepts either a Playwright-compatible selector string (e.g.
-     * `'button:has-text("Buy now")'`) or a built `Locator`. The click point
-     * inside the element is Gaussian-distributed around the center.
+     * `target` accepts a Playwright-compatible selector string (e.g.
+     * `'button:has-text("Buy now")'`), a built `Locator`, or a raw `Point`.
+     * For element targets the click point is Gaussian-distributed around the
+     * center; for a raw `Point` the exact coordinates are clicked. The
+     * `Point` form is the fallback for things with no clean selector —
+     * icon-only buttons, canvas, SVG — where you can see the pixel position
+     * but can't address the element.
+     *
+     * In `speed: 'instant'`, all humanization is skipped: element targets use
+     * Playwright's native `locator.click()`; a `Point` dispatches one
+     * `mouse.click()` at the coordinates.
+     */
+    click(target: MouseTarget): Promise<void>;
+    /**
+     * Right-click `target` — opens a native context menu. Same Bezier-path
+     * motion and hover dwell as `click()`; only the dispatched button differs.
+     * Accepts the same selector / `Locator` / `Point` targets as `click()`.
+     *
+     * In `speed: 'instant'`, element targets fall back to
+     * `locator.click({ button: 'right' })`; a `Point` dispatches one
+     * `mouse.click({ button: 'right' })` at the coordinates.
+     */
+    rightClick(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
+     * (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'`, all humanization is skipped and Playwright's
-     * native `locator.click()` is used directly.
+     * In `speed: 'instant'`, dispatches `mouse.down → move → up` at the
+     * resolved coordinates without humanized motion.
      */
-    click(target: Locator | string): Promise<void>;
+    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 +532,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
@@ -508,6 +678,102 @@ interface Human {
      */
     record(fn: () => Promise<void>): Promise<Recording>;
     record(options: HumanRecordOptions, fn: () => Promise<void>): Promise<Recording>;
+    /**
+     * Take a screenshot of the page. Forwards to `page.screenshot(options)`
+     * unchanged — see Playwright docs for the full options shape.
+     *
+     * Not a humanized action: no plugin events fire. Pure ergonomic
+     * re-export so `human.*` stays a single surface.
+     */
+    screenshot(options?: Parameters<Page['screenshot']>[0]): Promise<Buffer>;
+    /**
+     * Visible text content of the page (`document.body.innerText`). Forwards
+     * to `page.innerText('body')`. Useful for AI agents that need to
+     * understand what's on screen without parsing HTML.
+     *
+     * For a region instead of the whole page, use `page.innerText(selector)`.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    pageText(): Promise<string>;
+    /**
+     * Full HTML of the page. Forwards to `page.content()`. Often large
+     * (50–500 KB on typical sites) — prefer {@link Human.pageText} when
+     * passing to an LLM unless structure matters.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    content(): Promise<string>;
+    /**
+     * Current URL of the page. Forwards to `page.url()`. Synchronous return
+     * because Playwright's underlying API is sync.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    url(): string;
+    /**
+     * Current document title. Forwards to `page.title()`.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    title(): Promise<string>;
+    /**
+     * Reload the current page. Forwards to `page.reload(options)`. Real-user
+     * analog of hitting the refresh button — the click motion is *not*
+     * humanized (we treat reload as navigation, not a cursor action).
+     *
+     * Plugins observe a `'reload'` action.
+     */
+    reload(options?: Parameters<Page['reload']>[0]): Promise<void>;
+    /**
+     * Navigate back in the browser history. Forwards to `page.goBack(options)`.
+     *
+     * Plugins observe a `'goBack'` action.
+     */
+    goBack(options?: Parameters<Page['goBack']>[0]): Promise<void>;
+    /**
+     * Navigate forward in the browser history. Forwards to
+     * `page.goForward(options)`.
+     *
+     * Plugins observe a `'goForward'` action.
+     */
+    goForward(options?: Parameters<Page['goForward']>[0]): Promise<void>;
+    /**
+     * Wait until the page reaches the specified load state. Forwards to
+     * `page.waitForLoadState(state, options)`. Common after a humanized
+     * click that triggers navigation — gives the page time to settle before
+     * the next action.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    waitForLoadState(state?: Parameters<Page['waitForLoadState']>[0], options?: Parameters<Page['waitForLoadState']>[1]): Promise<void>;
+    /**
+     * Wait until the page's URL matches `url` (string, RegExp, or predicate).
+     * Forwards to `page.waitForURL(url, options)`. Common post-action wait
+     * (e.g. after `human.click('#login')`, wait for `/dashboard`).
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    waitForURL(url: Parameters<Page['waitForURL']>[0], options?: Parameters<Page['waitForURL']>[1]): Promise<void>;
+    /**
+     * Resize the viewport. Forwards to `page.setViewportSize(size)`. Useful
+     * for testing responsive layouts or switching between breakpoints
+     * mid-session.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /**
+     * Render the page as a PDF. Forwards to `page.pdf(options)`. Chromium
+     * only; works most reliably in headless mode (in headed mode, Playwright
+     * silently switches to a print-style render).
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    pdf(options?: Parameters<Page['pdf']>[0]): Promise<Buffer>;
 }
 /** Options for {@link Human.record}. */
 interface HumanRecordOptions {
@@ -545,4 +811,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()`).
@@ -385,14 +458,69 @@ interface Human {
     /**
      * Move the mouse along a humanized Bezier path to `target` and click.
      *
-     * `target` accepts either a Playwright-compatible selector string (e.g.
-     * `'button:has-text("Buy now")'`) or a built `Locator`. The click point
-     * inside the element is Gaussian-distributed around the center.
+     * `target` accepts a Playwright-compatible selector string (e.g.
+     * `'button:has-text("Buy now")'`), a built `Locator`, or a raw `Point`.
+     * For element targets the click point is Gaussian-distributed around the
+     * center; for a raw `Point` the exact coordinates are clicked. The
+     * `Point` form is the fallback for things with no clean selector —
+     * icon-only buttons, canvas, SVG — where you can see the pixel position
+     * but can't address the element.
+     *
+     * In `speed: 'instant'`, all humanization is skipped: element targets use
+     * Playwright's native `locator.click()`; a `Point` dispatches one
+     * `mouse.click()` at the coordinates.
+     */
+    click(target: MouseTarget): Promise<void>;
+    /**
+     * Right-click `target` — opens a native context menu. Same Bezier-path
+     * motion and hover dwell as `click()`; only the dispatched button differs.
+     * Accepts the same selector / `Locator` / `Point` targets as `click()`.
+     *
+     * In `speed: 'instant'`, element targets fall back to
+     * `locator.click({ button: 'right' })`; a `Point` dispatches one
+     * `mouse.click({ button: 'right' })` at the coordinates.
+     */
+    rightClick(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
+     * (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'`, all humanization is skipped and Playwright's
-     * native `locator.click()` is used directly.
+     * In `speed: 'instant'`, dispatches `mouse.down → move → up` at the
+     * resolved coordinates without humanized motion.
      */
-    click(target: Locator | string): Promise<void>;
+    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 +532,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
@@ -508,6 +678,102 @@ interface Human {
      */
     record(fn: () => Promise<void>): Promise<Recording>;
     record(options: HumanRecordOptions, fn: () => Promise<void>): Promise<Recording>;
+    /**
+     * Take a screenshot of the page. Forwards to `page.screenshot(options)`
+     * unchanged — see Playwright docs for the full options shape.
+     *
+     * Not a humanized action: no plugin events fire. Pure ergonomic
+     * re-export so `human.*` stays a single surface.
+     */
+    screenshot(options?: Parameters<Page['screenshot']>[0]): Promise<Buffer>;
+    /**
+     * Visible text content of the page (`document.body.innerText`). Forwards
+     * to `page.innerText('body')`. Useful for AI agents that need to
+     * understand what's on screen without parsing HTML.
+     *
+     * For a region instead of the whole page, use `page.innerText(selector)`.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    pageText(): Promise<string>;
+    /**
+     * Full HTML of the page. Forwards to `page.content()`. Often large
+     * (50–500 KB on typical sites) — prefer {@link Human.pageText} when
+     * passing to an LLM unless structure matters.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    content(): Promise<string>;
+    /**
+     * Current URL of the page. Forwards to `page.url()`. Synchronous return
+     * because Playwright's underlying API is sync.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    url(): string;
+    /**
+     * Current document title. Forwards to `page.title()`.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    title(): Promise<string>;
+    /**
+     * Reload the current page. Forwards to `page.reload(options)`. Real-user
+     * analog of hitting the refresh button — the click motion is *not*
+     * humanized (we treat reload as navigation, not a cursor action).
+     *
+     * Plugins observe a `'reload'` action.
+     */
+    reload(options?: Parameters<Page['reload']>[0]): Promise<void>;
+    /**
+     * Navigate back in the browser history. Forwards to `page.goBack(options)`.
+     *
+     * Plugins observe a `'goBack'` action.
+     */
+    goBack(options?: Parameters<Page['goBack']>[0]): Promise<void>;
+    /**
+     * Navigate forward in the browser history. Forwards to
+     * `page.goForward(options)`.
+     *
+     * Plugins observe a `'goForward'` action.
+     */
+    goForward(options?: Parameters<Page['goForward']>[0]): Promise<void>;
+    /**
+     * Wait until the page reaches the specified load state. Forwards to
+     * `page.waitForLoadState(state, options)`. Common after a humanized
+     * click that triggers navigation — gives the page time to settle before
+     * the next action.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    waitForLoadState(state?: Parameters<Page['waitForLoadState']>[0], options?: Parameters<Page['waitForLoadState']>[1]): Promise<void>;
+    /**
+     * Wait until the page's URL matches `url` (string, RegExp, or predicate).
+     * Forwards to `page.waitForURL(url, options)`. Common post-action wait
+     * (e.g. after `human.click('#login')`, wait for `/dashboard`).
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    waitForURL(url: Parameters<Page['waitForURL']>[0], options?: Parameters<Page['waitForURL']>[1]): Promise<void>;
+    /**
+     * Resize the viewport. Forwards to `page.setViewportSize(size)`. Useful
+     * for testing responsive layouts or switching between breakpoints
+     * mid-session.
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /**
+     * Render the page as a PDF. Forwards to `page.pdf(options)`. Chromium
+     * only; works most reliably in headless mode (in headed mode, Playwright
+     * silently switches to a print-style render).
+     *
+     * Not a humanized action: no plugin events fire.
+     */
+    pdf(options?: Parameters<Page['pdf']>[0]): Promise<Buffer>;
 }
 /** Options for {@link Human.record}. */
 interface HumanRecordOptions {
@@ -545,4 +811,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 };