@humanjs/playwright 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,196 @@
-import { PersonalityConfig, HumanPlugin, Point, Personality } from '@humanjs/core';
-export { ActionResult, ActionType, BezierPathOptions, DwellProfile, HumanAction, HumanPlugin, HumanizePathOptions, KnownActionType, MouseProfile, Personality, PersonalityConfig, PersonalityExtension, PluginContext, Point, PresetName, ReadingProfile, Rng, TypingProfile, applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, createRng, distracted, fast, humanizePath, precise, resolvePersonality } from '@humanjs/core';
-import { Locator, Page } from 'playwright';
+import { ReadKind, PersonalityConfig, HumanPlugin, Point, 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 } from '@humanjs/core';
+import { Locator, BrowserContext, Page } from 'playwright';
+
+/**
+ * What to read:
+ *  - `string`: a Playwright-compatible selector (matches `click()` / `type()`).
+ *    The element's `innerText` is resolved and word-counted.
+ *  - `Locator`: same, but you already have a Locator handle.
+ *  - `{ text }`: literal text (you have the string in hand, no selector).
+ *  - `{ words }`: pre-counted (bypass extraction entirely).
+ */
+type ReadTarget = string | Locator | {
+    readonly text: string;
+} | {
+    readonly words: number;
+};
+interface ReadOptions {
+    /**
+     * Reading mode. Built-in multipliers on top of `personality.reading.wpm`:
+     *  - `'prose'`: 1.0× (default for non-code targets)
+     *  - `'code'`:  0.4× (default when target is a `<pre>` or `<code>` element)
+     *  - `'scan'`:  1.8× (skim mode, must be explicit)
+     *
+     * **Smart defaults:** when `kind` is omitted AND the target is a Locator/
+     * selector, the adapter inspects the resolved element's tag — `<pre>` and
+     * `<code>` auto-detect as `'code'`; everything else as `'prose'`. An
+     * explicit `kind` always wins over auto-detection.
+     */
+    readonly kind?: ReadKind;
+    /** Override the effective WPM multiplier directly. Wins over `kind`. */
+    readonly wpmMultiplier?: number;
+    /**
+     * For selector/Locator targets: scroll the element into the viewport
+     * before the dwell. A user can't read what isn't on screen. Defaults to
+     * `false` — in most flows the caller has already scrolled there.
+     */
+    readonly scrollIntoView?: boolean;
+    /**
+     * For selector/Locator targets: trace a humanized cursor path through the
+     * target's bounding box while the dwell elapses, like an eye tracking
+     * lines of text. Off by default — opt in when you want the humanization
+     * signal (or when reading-time mouseover behavior matters, e.g. tooltips
+     * that activate while a real user's cursor moves over the content).
+     *
+     * The scan path is generated by `planReadingScan` from `@humanjs/core`
+     * (same deterministic-by-seed contract as the rest of the library) and
+     * walked over the computed dwell duration, so motion finishes exactly as
+     * the read does. The cursor's tracked position is updated to the scan's
+     * endpoint so the next click starts from where the eye landed.
+     *
+     * Ignored when the target is `{ text }` or `{ words }` (no bounding box).
+     */
+    readonly withMotion?: boolean;
+}
+/** Outcome of a read, returned to the caller for observability. */
+interface ReadResult {
+    /** Number of words counted (after whitespace splitting / from caller's `{ words }`). */
+    readonly words: number;
+    /** Sleep duration in ms. Zero in `speed: 'instant'` or for zero-word inputs. */
+    readonly durationMs: number;
+    /** Final reading kind used (after auto-detection + explicit-override resolution). */
+    readonly kind: ReadKind;
+}
+
+/**
+ * What / where to scroll. The chosen axis (`'y'` by default, `'x'` via
+ * `options.axis`) decides whether targets resolve along the vertical or
+ * horizontal axis.
+ *
+ *  - `'natural'`: scroll one viewport along the chosen axis (default).
+ *  - `'end'`: scroll to the far edge (bottom for `'y'`, right for `'x'`).
+ *  - `'top'`: scroll to the origin (top for `'y'`, left for `'x'`).
+ *  - `string`: a Playwright-compatible selector — scroll until in view.
+ *  - `Locator`: same, but you already have a Locator handle.
+ *  - `{ by: number }`: relative pixel delta (negative = up / left).
+ *  - `{ to: number }`: absolute scroll position on the chosen axis.
+ */
+type ScrollTarget = 'natural' | 'end' | 'top' | string | Locator | {
+    readonly by: number;
+} | {
+    readonly to: number;
+};
+interface ScrollOptions {
+    /**
+     * Force an overshoot + correction even if the personality wouldn't choose
+     * one. Useful when you want the humanization signal regardless of
+     * personality (e.g. demos).
+     */
+    readonly overshoot?: boolean;
+    /**
+     * Disable mid-scroll micro-pauses. Defaults to `true` (pauses enabled).
+     * Set `false` for the smoothest possible motion.
+     */
+    readonly withPauses?: boolean;
+    /**
+     * For element targets only: where to align the element along the chosen
+     * axis when the scroll ends. Mirrors `scrollIntoView({ block })`.
+     * Defaults to `'start'`.
+     *
+     * - `'start'`: element's leading edge aligns with the viewport's leading
+     *    edge (top for `axis: 'y'`, left for `axis: 'x'`)
+     * - `'center'`: element centers in the viewport
+     * - `'end'`: element's trailing edge aligns with the viewport's trailing
+     *    edge (bottom for `'y'`, right for `'x'`)
+     * - `'nearest'`: do the minimum scroll — stay put if the element is
+     *    already fully visible, otherwise scroll to the closest edge
+     */
+    readonly block?: 'start' | 'center' | 'end' | 'nearest';
+    /**
+     * Scroll inside a scrollable container instead of the page. Accepts a
+     * Playwright-compatible selector or a built `Locator`. Every scroll
+     * semantic (`'natural'`, `'top'`, `'end'`, `{ by }`, `{ to }`, element
+     * targets, `block` alignment) applies relative to the container.
+     *
+     * In humanized speed modes, the cursor parks over the container's
+     * center so the visible cursor reads as "human hand on the wheel"
+     * (when paired with `installMouseHelper`), and each planned segment
+     * advances the container's `scrollLeft` / `scrollTop` directly. Direct
+     * property assignment is more reliable than dispatching wheel events
+     * into nested overflow containers — Playwright's synthetic wheel
+     * events don't always route past the cursor element. In `'instant'`
+     * mode, the container's scroll position is set with a single
+     * `scrollTo` call.
+     *
+     * Common use: chat threads, modal bodies, infinite-scroll feeds, any
+     * `<div style="overflow-y: auto">` that owns its own scrollbar.
+     */
+    readonly within?: string | Locator;
+    /**
+     * Which axis to scroll along. Defaults to `'y'` (vertical).
+     *
+     * Set `'x'` for horizontal scrolling — carousels, kanban boards,
+     * sideways galleries. Every target shape still works: `'natural'`
+     * scrolls one viewport-width right, `'top'` jumps to scrollLeft 0,
+     * `'end'` to (scrollWidth - clientWidth), `{ by }` / `{ to }` apply to
+     * the X-axis, and element targets scroll until the element is visible
+     * horizontally.
+     */
+    readonly axis?: 'x' | 'y';
+}
+/** Outcome of a scroll, returned to the caller for observability. */
+interface ScrollResult {
+    /** Starting scroll position along the chosen axis (scrollY or scrollX). */
+    readonly from: number;
+    /** Final scroll position the scroll aimed for, along the chosen axis. */
+    readonly to: number;
+    /** Signed pixel distance (`to - from`). */
+    readonly distance: number;
+    /** Total elapsed dwell + motion time in ms. Zero in `speed: 'instant'`. */
+    readonly durationMs: number;
+}
+
+/** Options for {@link installMouseHelper}. */
+interface InstallMouseHelperOptions {
+    /** Cursor fill color. Defaults to the HumanJS amber `#f5a55c`. */
+    readonly color?: string;
+    /** Cursor visual size in pixels. Defaults to 22. */
+    readonly size?: number;
+    /**
+     * Render a ripple at each `mousedown` position so clicks read on video.
+     * Defaults to `true`.
+     */
+    readonly showClicks?: boolean;
+    /** Halo opacity behind the cursor. Defaults to `0.18`. */
+    readonly haloOpacity?: number;
+}
+/**
+ * Installs a visual cursor overlay that follows every `mousemove` on each
+ * page in the target. Real synthetic motion from Playwright (e.g.
+ * `human.click()`, `human.read(..., { withMotion: true })`) is *already*
+ * happening — the page just doesn't render a system cursor for it. This
+ * helper injects a HumanJS-styled SVG cursor that listens to mousemove
+ * events and follows them, making the motion visible in headed demos and
+ * screen recordings.
+ *
+ * Re-runs on every navigation via `addInitScript`, so the overlay survives
+ * page reloads. Idempotent — guard flag on `window` prevents double-install.
+ *
+ * Accepts either a `Page` (overlay applies to that page) or a
+ * `BrowserContext` (overlay applies to every page in the context, including
+ * pages opened later).
+ *
+ * @example
+ * ```ts
+ * const browser = await chromium.launch({ headless: false });
+ * const context = await browser.newContext();
+ * await installMouseHelper(context);
+ * const page = await context.newPage();
+ * // human-driven actions are now visible in the page
+ * ```
+ */
+declare function installMouseHelper(target: BrowserContext | Page, options?: InstallMouseHelperOptions): Promise<void>;
 
 /**
  * How fast the humanized session runs.
@@ -49,6 +239,77 @@ interface Human {
      * native `locator.click()` is used directly.
      */
     click(target: Locator | string): Promise<void>;
+    /**
+     * Type `value` into `target` with humanized per-key timing, optional typo
+     * injection (with backspace recovery), and occasional think-pauses.
+     *
+     * Per-key `keydown`/`press`/`up` events fire for each character, so
+     * handlers like autocomplete dropdowns still receive every keystroke.
+     *
+     * In `speed: 'instant'`, falls back to `locator.pressSequentially` with
+     * zero inter-key delay — events still fire, but humanization is skipped.
+     */
+    type(target: Locator | string, value: string): 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
+     * that pause from word count + the personality's reading WPM (+ jitter).
+     *
+     * **Targets:**
+     *  - `string`: a Playwright-compatible selector (matches `click()`/`type()`).
+     *  - `Locator`: a pre-built Locator.
+     *  - `{ text }`: literal text in hand (no DOM lookup).
+     *  - `{ words }`: pre-counted — skip text extraction entirely.
+     *
+     * **Smart defaults** (only when the caller doesn't override):
+     *  - `kind` auto-detects as `'code'` for `<pre>` and `<code>` tags;
+     *    everything else falls back to `'prose'`. Explicit `kind` always wins.
+     *  - `scrollIntoView: false` — most flows already scrolled to the content.
+     *
+     * Plugins observe `'read'` actions with `{ target, words, kind }` in params.
+     * The text content itself is never echoed — passwords, tokens, and other
+     * sensitive strings stay out of telemetry by default.
+     *
+     * In `speed: 'instant'`, dwell collapses to 0 ms but the action still fires
+     * so observability stays consistent.
+     *
+     * Returns a {@link ReadResult} with the word count, final kind (after
+     * auto-detection), and total dwell duration — useful for assertions in
+     * tests or for surfacing reading metadata to a UI.
+     */
+    read(target: ReadTarget, options?: ReadOptions): Promise<ReadResult>;
+    /**
+     * Scroll the page (or a scrollable container) humanly. Multi-segment
+     * motion with a bell-curve velocity profile, optional mid-scroll
+     * micro-pauses, and (for the `distracted` personality) the occasional
+     * overshoot + correction.
+     *
+     * **Targets:**
+     *  - `'natural'` (default): scroll one viewport in the chosen axis
+     *  - `'end'` / `'top'`: jump to the document/container edges, humanized
+     *  - `string`: a Playwright-compatible selector — scroll until in view
+     *  - `Locator`: same, but with a pre-built handle
+     *  - `{ by: n }`: relative pixel delta (negative = up / left)
+     *  - `{ to: n }`: absolute scroll position on the chosen axis
+     *
+     * **Options:** `axis: 'x' | 'y'` (default `'y'`) picks the direction;
+     * `within: selector | Locator` scopes the scroll to a scrollable
+     * container; `block: 'start' | 'center' | 'end' | 'nearest'` aligns
+     * element targets; `overshoot` / `withPauses` toggle individual
+     * humanization signals.
+     *
+     * Plugins observe `'scroll'` actions with `{ target }` in
+     * `beforeAction`'s params (a human-readable description of the target).
+     * The full {@link ScrollResult} (`from` / `to` / `distance` /
+     * `durationMs`) is available via `afterAction`'s `result` argument.
+     *
+     * In `speed: 'instant'`, the page (or container) is moved with a single
+     * `scrollTo` call. No wheel events, no segments — but the action still
+     * fires for observability.
+     *
+     * Returns a {@link ScrollResult} for assertions in tests.
+     */
+    scroll(target?: ScrollTarget, options?: ScrollOptions): Promise<ScrollResult>;
 }
 /**
  * Creates a humanized session bound to a Playwright `Page`.
@@ -71,4 +332,4 @@ interface Human {
  */
 declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
 
-export { type CreateHumanOptions, type Human, type Speed, createHuman };
+export { type CreateHumanOptions, type Human, type InstallMouseHelperOptions, type ReadOptions, type ReadResult, type ReadTarget, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, createHuman, installMouseHelper };