@humanjs/playwright 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,350 @@
-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, sleep } from '@humanjs/core';
+import { Locator, BrowserContext, Page } from 'playwright';
+export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } 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. **Defaults to `true`** — "reading" implies looking, and
+     * looking implies motion. Pass `false` to skip motion when you only
+     * care about the temporal pattern (typical AI-agent use case where
+     * the cursor position is irrelevant).
+     *
+     * 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;
+}
+
+/**
+ * A captured frame in the timer-based capture session. `tMs` is the
+ * wall-clock offset (ms) from the capture start.
+ */
+interface CapturedFrame {
+    readonly path: string;
+    readonly tMs: number;
+}
+/** Outcome of a finalized capture session. */
+interface CaptureResult {
+    readonly dir: string;
+    readonly frames: readonly CapturedFrame[];
+    readonly startedAtMs: number;
+    readonly stoppedAtMs: number;
+    readonly format: 'jpeg' | 'png';
+    readonly fps: number;
+    /**
+     * Removes the temp directory + all frames. Called by `Recording.dispose()`
+     * and by the sweep-on-exit handler — not by the exporters, which are
+     * repeatable and read the frames without consuming them. Also called
+     * directly by the error path in `human.record()` when the callback throws.
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * Encoding quality preset. Picks the per-frame capture quality + the
+ * ffmpeg encode settings used to assemble them into a video.
+ *
+ * - `'fast'` — JPEG q=85, CRF 23, preset fast (iteration)
+ * - `'standard'` — JPEG q=90, CRF 20, preset fast (balanced)
+ * - `'high'` (default) — JPEG q=95, CRF 18, preset slow, tune animation (marketing-grade)
+ * - `'lossless'` — PNG capture, CRF 12, preset veryslow (archival; huge temp files)
+ */
+type RecordingQuality = 'fast' | 'high' | 'lossless' | 'standard';
+/** ffmpeg `-preset` values, ordered from fastest to slowest. */
+type FfmpegPreset = 'fast' | 'faster' | 'medium' | 'slow' | 'slower' | 'superfast' | 'ultrafast' | 'veryfast' | 'veryslow';
+/** ffmpeg `-tune` values for libx264. */
+type FfmpegTune = 'animation' | 'fastdecode' | 'film' | 'grain' | 'stillimage' | 'zerolatency';
+/** Options for {@link Recording.toVideo}. */
+interface ToVideoOptions {
+    /** Encoding quality preset. Defaults to `'high'`. */
+    readonly quality?: RecordingQuality;
+    /** Override CRF (0–51, lower = better). Defaults to the quality preset's CRF. */
+    readonly crf?: number;
+    /** Override ffmpeg `-preset`. Defaults to the quality preset's preset. */
+    readonly preset?: FfmpegPreset;
+    /** Override ffmpeg `-tune`. Defaults to the quality preset's tune (if any). */
+    readonly tune?: FfmpegTune;
+}
+/** Options for {@link Recording.toGif}. */
+interface ToGifOptions {
+    /**
+     * Frames per second of the output GIF. Defaults to `15` — high enough for
+     * smooth motion in most renderers, low enough to keep file size sane.
+     * Renderers cap GIF playback around 50fps anyway.
+     */
+    readonly fps?: number;
+    /**
+     * Scale the GIF to this width (pixels). Height is computed to preserve
+     * aspect ratio. Omit to keep the source viewport size — but most embedded
+     * GIFs (README, PR, Slack) look fine at 640–960px and weigh a fraction.
+     */
+    readonly width?: number;
+}
+/** One action captured during a recording, as emitted in {@link Timeline.events}. */
+interface TimelineEvent {
+    readonly type: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    /** Offset (ms) from the recording start when the action began. */
+    readonly tMs: number;
+    readonly durationMs: number;
+    /** Error message, present only if the action threw. */
+    readonly error?: string;
+}
+/** Structured action timeline of a recording. */
+interface Timeline {
+    readonly version: 1;
+    readonly personality: string;
+    readonly seed: string | null;
+    readonly speed: string;
+    readonly durationMs: number;
+    readonly events: readonly TimelineEvent[];
+}
+/** Metadata passed from `human.record()` into the Recording constructor. */
+interface RecordingTimelineSource {
+    readonly personality: string;
+    readonly seed: string | null;
+    readonly speed: string;
+    readonly events: readonly TimelineEvent[];
+}
+/**
+ * A recorded window of a humanized session. Returned by `human.record(cb)`.
+ *
+ * A Recording can hold a frame capture (`hasVideo === true`) OR be
+ * timeline-only (`hasVideo === false`). `toVideo()` / `toGif()` require a
+ * capture; `toTimeline()` and `.timeline` work either way.
+ *
+ * The video exporters are repeatable and interleavable — they read the
+ * captured frames without consuming them. Calling `dispose()` is OPTIONAL:
+ * the captured-frames temp dir is also swept by a `process.on('exit')`
+ * handler installed on first use, so casual scripts can skip it entirely.
+ * Call `dispose()` (or use `await using`) when you want to release the
+ * frames proactively — long-running services, batch jobs, etc.
+ */
+declare class Recording {
+    #private;
+    constructor(capture: CaptureResult | null, windowStartMs: number, windowEndMs: number, timelineSource: RecordingTimelineSource);
+    /** Wall-clock duration of the recorded window. */
+    get durationMs(): number;
+    /** True if frames were captured during this recording. */
+    get hasVideo(): boolean;
+    /**
+     * The structured action timeline of this recording — same data that
+     * `toTimeline()` writes to disk.
+     */
+    get timeline(): Timeline;
+    /**
+     * Assembles the captured frames into a video at `outputPath`. The output
+     * format is inferred from the extension — `.mp4` (H.264, re-encoded
+     * with the configured quality) or `.webm` (VP9).
+     *
+     * Repeatable and interleavable with `toGif()` — the frame source is read,
+     * not consumed. Frames live until you call `dispose()` (or `await using`
+     * goes out of scope, or the process exits and the OS reaps `tmpdir`).
+     *
+     * @returns the resolved output path.
+     */
+    toVideo(outputPath: string, options?: ToVideoOptions): Promise<string>;
+    /**
+     * Assembles the captured frames into an animated GIF at `outputPath`.
+     * Optimized for embedding in READMEs, PRs, Slack, and docs — uses a
+     * per-recording palette (`palettegen` + `paletteuse`) with Bayer dithering
+     * so gradients stay smooth without exploding the file size.
+     *
+     * Repeatable and interleavable with `toVideo()` — call them in any order,
+     * any number of times. Frames live until you call `dispose()`.
+     *
+     * @returns the resolved output path.
+     */
+    toGif(outputPath: string, options?: ToGifOptions): Promise<string>;
+    /**
+     * Writes the structured action timeline to `outputPath` as JSON.
+     * Independent of `toVideo()` / `toGif()` — call before, after, in between,
+     * or instead. Safe to call multiple times. Unaffected by `dispose()`
+     * (the timeline lives in memory, not in the captured-frames temp dir).
+     *
+     * @returns the resolved output path.
+     */
+    toTimeline(outputPath: string): Promise<string>;
+    /**
+     * Releases the captured-frames temp directory. After this call, `toVideo()`
+     * and `toGif()` throw — but `toTimeline()` and the in-memory `timeline`
+     * still work because those don't depend on the frames.
+     *
+     * **Optional.** A process-exit handler also sweeps any un-disposed frame
+     * dirs, so casual scripts can skip this entirely. Call it explicitly when
+     * you want to release frames proactively (long-running services, batch
+     * jobs, or anywhere you want predictable disk usage).
+     *
+     * Idempotent. Safe to call on a Recording that never had a capture
+     * (timeline-only mode) — no-op there.
+     *
+     * Also wired to `Symbol.asyncDispose`, so the explicit-resource-management
+     * `await using` syntax (TypeScript ≥ 5.2 / Node ≥ 20.4) works:
+     *
+     * ```ts
+     * await using rec = await human.record(fn);
+     * await rec.toVideo('demo.mp4');
+     * await rec.toGif('demo.gif');
+     * // frames cleaned up automatically when `rec` goes out of scope
+     * ```
+     */
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * 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;
+}
+declare function installMouseHelper(target: BrowserContext | Page, options?: InstallMouseHelperOptions): Promise<void>;
 
 /**
  * How fast the humanized session runs.
@@ -49,6 +393,136 @@ 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>;
+    /**
+     * Pause for `ms` milliseconds. Equivalent to importing `sleep` from
+     * `@humanjs/playwright` and calling it — exposed on the Human instance
+     * so users who already have `human` in scope don't need an extra import.
+     *
+     * Not a humanized action: this is a raw `setTimeout` wait, not scaled
+     * by personality or speed mode, and no plugin events fire. Use it for
+     * generic pacing between humanized actions.
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Records `fn`'s actions. Returns a {@link Recording} you can export
+     * to mp4/webm video (`toVideo`), JSON timeline (`toTimeline`), or both.
+     *
+     * By default, frames are captured from the browser via timer-polled
+     * `page.screenshot()` — fully controllable quality, not limited by
+     * Playwright's recordVideo bitrate ceiling. Pass `{ video: false }` to
+     * skip capture entirely (timeline-only mode, zero video overhead).
+     *
+     * Plugins observe `'record'` in `beforeAction` / `afterAction` so
+     * recording shows up alongside the other primitives in observability
+     * pipelines.
+     *
+     * Single-use per session: `Recording.toVideo()` finalizes the captured
+     * frames, so calling `human.record()` twice on the same human throws.
+     *
+     * @example
+     * ```ts
+     * // Default: video + timeline
+     * const rec = await human.record(async () => {
+     *   await human.click('#login');
+     * });
+     * await rec.toVideo('demo.mp4');
+     * await rec.toTimeline('demo.json');
+     *
+     * // Timeline-only, no video overhead
+     * const rec = await human.record({ video: false }, async () => {
+     *   await human.click('#login');
+     * });
+     * await rec.toTimeline('demo.json');
+     * ```
+     */
+    record(fn: () => Promise<void>): Promise<Recording>;
+    record(options: HumanRecordOptions, fn: () => Promise<void>): Promise<Recording>;
+}
+/** Options for {@link Human.record}. */
+interface HumanRecordOptions {
+    /**
+     * Whether to capture frames for video output. Defaults to `true`.
+     * Set to `false` for timeline-only recordings (no capture loop, no
+     * temp files, no encoding overhead — `toTimeline()` still works).
+     */
+    readonly video?: boolean;
+    /**
+     * Capture quality preset. Controls per-frame JPEG quality (or PNG for
+     * lossless) AND the ffmpeg encode settings used by `toVideo()`.
+     * Defaults to `'high'`. Ignored when `video: false`.
+     */
+    readonly quality?: RecordingQuality;
 }
 /**
  * Creates a humanized session bound to a Playwright `Page`.
@@ -71,4 +545,4 @@ interface Human {
  */
 declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
 
-export { type CreateHumanOptions, type Human, type Speed, createHuman };
+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 };