@humanjs/playwright 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -458,21 +458,29 @@ 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 and Playwright's
-     * native `locator.click()` is used directly.
+     * 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: Locator | string): Promise<void>;
+    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'`, falls back to `locator.click({ button: 'right' })`.
+     * 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: Locator | string): Promise<void>;
+    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
@@ -670,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 {

package/dist/index.d.ts

@@ -458,21 +458,29 @@ 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 and Playwright's
-     * native `locator.click()` is used directly.
+     * 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: Locator | string): Promise<void>;
+    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'`, falls back to `locator.click({ button: 'right' })`.
+     * 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: Locator | string): Promise<void>;
+    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
@@ -670,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 {

package/dist/index.js

@@ -320,15 +320,22 @@ function clamp(value, min, max) {
 // src/mouse/index.ts
 async function executeClick(target, ctx, options = {}) {
   const button = options.button ?? "left";
-  const locator = typeof target === "string" ? ctx.page.locator(target) : target;
   if (ctx.speed === "instant") {
-    const box = await locator.boundingBox();
+    if (isPoint(target)) {
+      await ctx.page.mouse.click(target.x, target.y, { button });
+      ctx.setMousePosition(target);
+      return { target };
+    }
+    const locator = typeof target === "string" ? ctx.page.locator(target) : target;
+    const box2 = await locator.boundingBox();
     await locator.click({ button });
-    const center = box ? { x: box.x + box.width / 2, y: box.y + box.height / 2 } : ctx.getMousePosition();
+    const center = box2 ? { x: box2.x + box2.width / 2, y: box2.y + box2.height / 2 } : ctx.getMousePosition();
     ctx.setMousePosition(center);
     return { target: center };
   }
-  const targetPoint = await moveToTarget(target, ctx, "click");
+  const { point: targetPoint, box } = await resolveTargetPointAndBox(target, ctx, "click");
+  await maybeMisclickBeat(ctx, box, targetPoint);
+  await walkBezierTo(targetPoint, ctx);
   const preClickMs = computeDwellTime(
     ctx.personality.dwell.preClickMs,
     ctx.personality.dwell.preClickJitter,
@@ -357,7 +364,7 @@ async function executeHover(target, ctx) {
     ctx.setMousePosition(center);
     return { target: center };
   }
-  const targetPoint = await moveToTarget(target, ctx, "hover");
+  const targetPoint = await moveToTarget(target, ctx);
   const dwellMs = computeDwellTime(
     ctx.personality.dwell.preClickMs,
     ctx.personality.dwell.preClickJitter,
@@ -440,10 +447,9 @@ async function executeMove(target, ctx) {
   ctx.setMousePosition(point);
   return { target: point };
 }
-async function moveToTarget(target, ctx, action) {
-  const box = await readBoxWithAutoScroll(target, ctx, action);
+async function moveToTarget(target, ctx) {
+  const box = await readBoxWithAutoScroll(target, ctx, "hover");
   const targetPoint = pickClickPoint(box, ctx.rng, ctx.personality.mouse.clickSpread);
-  if (action === "click") await maybeMisclickBeat(ctx, box, targetPoint);
   await walkBezierTo(targetPoint, ctx);
   return targetPoint;
 }
@@ -1428,6 +1434,52 @@ async function createHuman(page, options = {}) {
         speed,
         events
       });
+    },
+    // ────────────────────────────────────────────────────────────────────
+    // Thin re-exports of common Playwright `Page` methods. See the `Human`
+    // interface for the rationale; implementations forward unchanged.
+    // ────────────────────────────────────────────────────────────────────
+    screenshot(opts) {
+      return page.screenshot(opts);
+    },
+    pageText() {
+      return page.innerText("body");
+    },
+    content() {
+      return page.content();
+    },
+    url() {
+      return page.url();
+    },
+    title() {
+      return page.title();
+    },
+    async reload(opts) {
+      await performAction({ type: "reload", params: {} }, async () => {
+        await page.reload(opts);
+      });
+    },
+    async goBack(opts) {
+      await performAction({ type: "goBack", params: {} }, async () => {
+        await page.goBack(opts);
+      });
+    },
+    async goForward(opts) {
+      await performAction({ type: "goForward", params: {} }, async () => {
+        await page.goForward(opts);
+      });
+    },
+    waitForLoadState(state, opts) {
+      return page.waitForLoadState(state, opts);
+    },
+    waitForURL(url, opts) {
+      return page.waitForURL(url, opts);
+    },
+    setViewportSize(size) {
+      return page.setViewportSize(size);
+    },
+    pdf(opts) {
+      return page.pdf(opts);
     }
   };
 }