@humanjs/playwright 0.5.0 → 0.6.0

package/README.md

@@ -1,5 +1,14 @@
 # @humanjs/playwright
 
+<p>
+  <a href="https://www.npmjs.com/package/@humanjs/playwright"><img alt="npm" src="https://img.shields.io/npm/v/@humanjs/playwright"></a>
+  <a href="https://www.npmjs.com/package/@humanjs/playwright"><img alt="downloads" src="https://img.shields.io/npm/dt/@humanjs/playwright"></a>
+  <a href="https://github.com/totigm/humanjs"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-totigm%2Fhumanjs-181717?logo=github"></a>
+  <a href="https://github.com/totigm/humanjs/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/totigm/humanjs/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/totigm/humanjs/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@humanjs/playwright"></a>
+  <a href="https://humanjs.dev"><img alt="docs" src="https://img.shields.io/badge/docs-humanjs.dev-emerald"></a>
+</p>
+
 Humanize Playwright sessions for AI agents, QA tests, and demos. Drop-in adapter for an existing Playwright `Page`.
 
 ## Install
@@ -364,6 +373,39 @@ await rec.toTimeline('session.json');   // works
 
 Every recording is a regular plugin action — `beforeAction` and `afterAction` observe `{ type: 'record' }` exactly like `'click'` or `'scroll'`.
 
+## Using your own browser or a persistent profile
+
+`createHuman(page)` wraps **any** Playwright `Page` — so reusing a saved login, your installed Chrome, or an already-running browser is just a matter of how you create that page. HumanJS adds nothing special here; these are standard Playwright entry points, collected so you don't have to hunt for them.
+
+**Persistent profile** — keep cookies, local storage, and logins across runs. The first run signs in; later runs are already authenticated:
+
+```ts
+import { chromium, createHuman } from '@humanjs/playwright';
+
+const context = await chromium.launchPersistentContext('./.humanjs-profile', {
+  headless: false,
+  channel: 'chrome', // optional: use installed Google Chrome instead of bundled Chromium
+});
+const page = context.pages()[0] ?? (await context.newPage());
+
+const human = await createHuman(page, { personality: 'careful' });
+// …drive the page; state persists in ./.humanjs-profile for next time
+```
+
+**Attach to an already-running browser** — drive a Chrome you started yourself, with all its existing tabs, extensions, and sessions. Launch Chrome with a debugging port first (`chrome --remote-debugging-port=9222`), then:
+
+```ts
+import { chromium, createHuman } from '@humanjs/playwright';
+
+const browser = await chromium.connectOverCDP('http://localhost:9222');
+const context = browser.contexts()[0];
+const page = context.pages()[0] ?? (await context.newPage());
+
+const human = await createHuman(page, { personality: 'careful' });
+```
+
+> **Heads up:** a persistent profile or a connected real browser carries whatever you're signed into. Driving it means the automation can act with those sessions' privileges — keep that in mind for anything sensitive, and be wary of pages that try to manipulate an agent into actions while logged in.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -325,15 +325,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,
@@ -362,7 +369,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,
@@ -445,10 +452,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;
 }
@@ -1433,6 +1439,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);
     }
   };
 }