@humanjs/playwright 0.3.0 → 0.5.0

package/README.md

@@ -13,8 +13,7 @@ pnpm add @humanjs/playwright playwright
 ## Quick start
 
 ```ts
-import { chromium } from 'playwright';
-import { createHuman } from '@humanjs/playwright';
+import { chromium, createHuman } from '@humanjs/playwright';
 
 const browser = await chromium.launch();
 const page = await browser.newPage();
@@ -46,6 +45,114 @@ await human.type('input[name="email"]', 'gonzalo@example.com');
 
 Pass a `seed` and every random decision (path curvature, typo placement, keystroke jitter) becomes reproducible. Same seed + same personality + same value = same keystrokes.
 
+### Primitives
+
+The full `Human` surface, at a glance. Each one fires real DOM events through Playwright; the humanization wraps the timing and the path, not the dispatch.
+
+| Primitive | Purpose |
+|---|---|
+| `goto(url)` | Navigate the page. |
+| `click(target)` | Bezier path → pre-click hover dwell → click. Occasionally near-misses (cursor wobble outside the target, then corrects) per `personality.mouse.misclickProbability`. |
+| `rightClick(target)` | Same as `click` but with `button: 'right'`. Fires `contextmenu`. Same near-miss behavior. |
+| `drag(from, to)` | Two-phase Bezier (to start → mouse down → curve to end → mouse up). Both endpoints accept `Locator \| string \| Point` — `Point` is essential for canvas / SVG / slider drags. Both endpoints independently near-miss per `misclickProbability` — a drag may wobble on the grab, the drop, both, or neither. |
+| `hover(target)` | Walk to the element and settle. No click. Hover-state UI (tooltips, dropdowns) fires. |
+| `move(target)` | Walk to a `Locator \| string \| Point`. Pure positional motion. No dwell, no element interaction — use this when you want the cursor parked somewhere with no implied click. |
+| `type(target, value)` | Clicks the field for focus, then per-key rhythm with optional typos + Backspace recovery. |
+| `paste(target, value)` | Clicks the field for focus, then `insertText` — instant insertion, no per-character timing. Cmd-V semantic. |
+| `press(key)` | Single key (`'Tab'`) or chord (`'Mod+S'`). See [Keyboard](#keyboard) below. |
+| `read(target)` | Dwell as a reader would. Cursor scans across the text in humanized mode. See [Reading](#reading). |
+| `scroll(target?)` | Multi-segment wheel motion, bell-curve velocity, optional mid-scroll pauses. See [Scrolling](#scrolling). |
+| `sleep(ms)` | Re-exported from `@humanjs/core` for convenience. |
+| `record(fn)` | Wrap a block and export as mp4 / gif / JSON. See [Recording](#recording). |
+
+Targets accept a CSS selector string or a Playwright `Locator`. `move` and `drag` additionally accept raw `Point` coordinates. Auto-scroll fires for any element-bound primitive when the target is outside the viewport — humanized scroll in normal speed modes, `scrollIntoViewIfNeeded` in `'instant'`.
+
+Near-miss (cursor wobble before committing — see `personality.mouse.misclickProbability`) applies to the primitives that commit a button event at the resolved coordinates: `click`, `rightClick`, both `drag` endpoints, and the implicit focus-acquiring click inside `type` / `paste` (the keystrokes themselves are unaffected). `hover`, `move`, `press`, `read`, and `scroll` never misclick, by design — a wobble would trigger handlers on the wrong element for `hover`, and would contradict the explicit-coordinate contract for `move`. The misclick is also skipped when the cursor is already on the target (no approach means no overshoot).
+
+### Keyboard
+
+```ts
+await human.press('Tab');               // single key
+await human.press('Mod+S');             // cross-platform save (Meta on Mac, Control elsewhere)
+await human.press('Cmd+Shift+P');       // literal Meta+Shift+P on every OS
+await human.press('Control+C');         // literal Ctrl+C
+await human.press('Shift+ArrowDown');   // extend selection down
+```
+
+`press` accepts a single key or a keyboard chord. IDE autocomplete enumerates every `Modifier+Key` combination — type `'Shift+'` and you get `Shift+A`, `Shift+B`, …, `Shift+Tab`, etc. as completions.
+
+**Modifier rules:**
+
+| Token | Resolves to | Notes |
+|---|---|---|
+| `Mod` / `CmdOrCtrl` / `CommandOrControl` | `Meta` on macOS, `Control` elsewhere | The right token for cross-platform app shortcuts. All three are aliases; `Mod` is shortest. |
+| `Cmd` / `Command` / `Meta` / `Win` / `Super` | `Meta` keycode | Literal — does **not** auto-translate to `Control`. Same physical key on every OS. |
+| `Ctrl` / `Control` | `Control` keycode | Literal — stays `Control` everywhere, so Mac-specific things like terminal `Ctrl+C` still work. |
+| `Alt` / `Option` / `Opt` | `Alt` keycode | Literal. |
+| `Shift` | `Shift` keycode | Literal. |
+
+Case-insensitive at runtime. Modifier typos (`'Mosd+S'`) are caught at compile time — the modifier union is closed.
+
+**Escape hatch for uncommon keys.** Uncommon keys (`'BracketLeft'`, `'NumpadAdd'`, locale-specific keys) and 3+ modifier chords aren't in the typed `KeyOrChord` union. Cast at the call site — the runtime parser handles them:
+
+```ts
+import type { KeyOrChord } from '@humanjs/playwright';
+
+await human.press('Mod+BracketLeft' as KeyOrChord);
+await human.press('Ctrl+Shift+Alt+K' as KeyOrChord);
+```
+
+Why a cast? Including a `(string & {})` escape hatch in the type collapses TypeScript's literal-template IntelliSense, so `'Shift+...'` completions disappear. Autocomplete wins for the 95% case; the cast handles the 5%.
+
+**Press does NOT move the cursor** — keyboard input dispatches against focus, not cursor position. Compose with `click` / `hover` / `move` when you need both.
+
+### Typing
+
+```ts
+await human.type('input[name="email"]', 'gonzalo@example.com');
+```
+
+`type` simulates a real keyboard. Per-key delays scale with the personality's typing speed (with jitter); the `distracted` personality occasionally injects QWERTY typos and recovers them with `Backspace`. Single ASCII characters route through Playwright's `keyboard.press` so per-key handlers (autocomplete, validation) fire; non-ASCII characters fall back to `keyboard.insertText` since `press` is keyboard-layout-aware and can't reliably synthesize `é` or `🎉` on every layout.
+
+Like every other element-bound primitive, `type` clicks the field first to focus it — a real user moves the cursor to the input and clicks; they don't teleport-focus a field. The implicit click is a sub-step of the `'type'` action, not its own timeline event.
+
+**Privacy.** The typed value is never echoed to plugin params. The `'type'` action surfaces only `{ target, length }` — by design, since this argument may carry passwords, tokens, or other secrets.
+
+In `'instant'` speed mode, the humanized loop is bypassed for Playwright's `locator.pressSequentially(value, { delay: 0 })` — per-key events still fire, just without the timing.
+
+### Pasting
+
+```ts
+await human.paste('textarea', longCodeBlock);
+```
+
+The Cmd-V semantic. `paste` clicks the field for focus (same mouse-led pattern as `type`), then dispatches the value via `page.keyboard.insertText` — instant, no per-character timing, the value lands in the field in a single beat.
+
+When to use which:
+
+- **`type`** — short strings where the per-key rhythm is the showcase (form fills, search queries, demo content). Slow on long input by design.
+- **`paste`** — long content where humanized typing would be slow and uninformative (code blocks, multi-paragraph text, anything you'd realistically Cmd-V into the field).
+
+`paste` does NOT fire the page's `paste` event. If you need that, drive it yourself: write to the clipboard, focus the field, then `human.press('Mod+V')`.
+
+**Privacy.** Same posture as `type` — `{ target, length }` only.
+
+### Dragging
+
+```ts
+await human.drag('#card-1', '#slot-3');                       // selector → selector
+await human.drag('#slider-thumb', { x: 800, y: 450 });        // selector → Point
+await human.drag('#card', locator);                           // any combination
+```
+
+Two-phase Bezier motion: walk to `from`, press the left button, curve to `to` with the button held, release. Each endpoint accepts a `Locator`, a CSS selector, or a raw `Point` coordinate.
+
+The `Point` form is essential for canvas / SVG drags where the destination isn't a DOM element — sliders, signature pads, freehand drawing tools. The selector-to-Point shape is the canonical "drag this thumb to that position" pattern.
+
+Both Bezier paths (start-to-`from` and `from`-to-`to`) are humanized independently with their own curvature and jitter, so drags don't trace robotic straight lines mid-flight.
+
+Auto-scroll fires on both endpoints when needed — if the destination is below the fold, the cursor scrolls to bring it into view before releasing, the way a real user would scroll-to-grab then scroll-to-drop. Raw `Point` endpoints opt out of auto-scroll (explicit coordinates are the caller's responsibility).
+
 ### Reading
 
 ```ts
@@ -75,15 +182,16 @@ await human.read('ul.changelog', { kind: 'scan' });    // explicit skim
 
 Explicit `kind` always wins over auto-detection.
 
-**Visible eye-scan motion** during the dwell:
+**Eye-scan cursor motion** runs during the dwell by default:
 
 ```ts
-await human.read('article', { withMotion: true });
+await human.read('article');                       // motion: on
+await human.read('article', { withMotion: false }); // motion: off
 ```
 
-The cursor walks a humanized L→R sweep through every line of rendered text and emits a small return-saccade between lines — same `mousemove` events a real reader would dispatch (so reading-time tooltip / hover handlers fire). Off by default.
+The cursor walks a humanized L→R sweep through every line of rendered text and emits a small return-saccade between lines — same `mousemove` events a real reader would dispatch (so reading-time tooltip / hover handlers fire). Pass `{ withMotion: false }` when you only care about the temporal pattern (typical AI-agent use case).
 
-For demos and screen recordings, pair `withMotion` with `installMouseHelper(page)` to render a visible cursor that follows the synthetic motion:
+For demos and screen recordings, pair it with `installMouseHelper(page)` to render a visible cursor that follows the synthetic motion:
 
 ```ts
 import { createHuman, installMouseHelper } from '@humanjs/playwright';
@@ -93,7 +201,7 @@ await page.goto('https://example.com/article');
 await installMouseHelper(page);
 
 const human = await createHuman(page, { personality: 'careful' });
-await human.read('article', { withMotion: true });
+await human.read('article');
 ```
 
 **Returns** a `ReadResult`:
@@ -171,6 +279,91 @@ In `speed: 'instant'`, the page jumps directly via `window.scrollTo` — no whee
 
 See [humanjs.dev](https://humanjs.dev) for the full feature set and personality reference.
 
+### Recording
+
+```ts
+import { chromium, createHuman, installMouseHelper } from '@humanjs/playwright';
+
+const browser = await chromium.launch({ headless: false });
+const context = await browser.newContext({ viewport: { width: 1920, height: 1080 } });
+const page = await context.newPage();
+
+// Visible cursor overlay so the recorded video shows mouse motion.
+await installMouseHelper(context);
+
+const human = await createHuman(page);
+
+const rec = await human.record(async () => {
+  await human.click('#login');
+  await human.type('#email', 'demo@humanjs.dev');
+});
+
+await rec.toVideo('demo.mp4');
+await rec.toTimeline('demo.json');
+await browser.close();
+```
+
+`human.record(cb)` polls `page.screenshot()` at the target FPS, writes each frame to a temp directory, then assembles them via ffmpeg when you call an exporter:
+
+- `rec.toVideo(path)` — `.mp4` (H.264 / yuv420p) or `.webm` (VP9)
+- `rec.toGif(path, { fps?, width? })` — palette-optimized animated GIF (`palettegen` + `paletteuse`, Bayer dither). Defaults to 15 fps, source viewport size.
+
+Both exporters are **repeatable and interleavable** — they read the captured frames, they don't consume them. Want an mp4 for the landing page *and* a GIF for the README from the same recording? Just call both:
+
+```ts
+const rec = await human.record(fn);
+await rec.toVideo('demo.mp4');
+await rec.toGif('demo.gif', { width: 720 });
+// No explicit cleanup needed for one-shot scripts — see below.
+```
+
+Captured frames live in a temp directory under `os.tmpdir()`. Cleanup happens automatically at process exit (a single `process.on('exit')` handler sweeps any un-disposed frame dirs), so casual scripts don't have to think about it. For long-running services, batch jobs, or anywhere you want predictable disk usage, release them proactively:
+
+```ts
+await rec.dispose();                  // explicit, idempotent
+// or with TS ≥ 5.2 / Node ≥ 20.4:
+await using rec = await human.record(fn);   // auto-disposes at scope exit
+```
+
+The same `Recording` exposes a **structured action timeline** of everything that happened during the callback:
+
+```ts
+await rec.toTimeline('session.json');   // → JSON on disk
+const timeline = rec.timeline;          // → in-memory object
+```
+
+The shape (`Timeline` with `personality`, `seed`, `speed`, `durationMs`, and an `events` array of `{ type, params, tMs, durationMs }`) is intended for observability pipelines, replay infrastructure, analytics, and debugger UIs. `toTimeline()` doesn't touch the browser context — call it before or after `toVideo()`, multiple times, in any order.
+
+**Quality presets** trade off file size, encoding time, and visual fidelity. Defaults to `'high'`:
+
+```ts
+await rec.toVideo('demo.mp4', { quality: 'high' });
+// 'fast'     — JPEG q=85, CRF 23, preset fast            (iteration)
+// 'standard' — JPEG q=90, CRF 20, preset fast            (balanced)
+// 'high'     — JPEG q=95, CRF 18, preset slow, animation (DEFAULT)
+// 'lossless' — PNG capture, CRF 12, preset veryslow      (archival)
+```
+
+Individual ffmpeg knobs (`crf`, `preset`, `tune`) can override the preset for fine-grained control.
+
+**Timeline-only mode** — skip the capture overhead entirely when you only need the action timeline:
+
+```ts
+const rec = await human.record({ video: false }, async () => {
+  await human.click('#login');
+});
+await rec.toTimeline('session.json');   // works
+// rec.toVideo('demo.mp4')               // throws with a clear message
+```
+
+**Lifecycle notes**:
+
+- Each session can produce **one** recording. `human.record()` throws if called twice on the same session — open a new context (and a new human) to record a separate clip.
+- `Recording.toVideo()` / `Recording.toGif()` are repeatable and interleavable. Frames live until `rec.dispose()` (or `await using` goes out of scope, or the process exits — a sweep-on-exit handler covers forgotten disposes).
+- For a one-call API that owns the entire lifecycle (launch → record → close), use [`@humanjs/recorder`](../recorder)'s `record(options, fn)` instead.
+
+Every recording is a regular plugin action — `beforeAction` and `afterAction` observe `{ type: 'record' }` exactly like `'click'` or `'scroll'`.
+
 ## License
 
 MIT