@humanjs/playwright 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,5 +1,511 @@
-import { resolvePersonality, createRng } from '@humanjs/core';
-export { blend, careful, createRng, distracted, fast, precise, resolvePersonality } from '@humanjs/core';
+import { resolvePersonality, createRng, planScroll, countWords, computeReadingDwellMs, planReadingScan, planTypeKeystrokes, bezierPath, humanizePath } from '@humanjs/core';
+export { applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, computeReadingDwellMs, countWords, createRng, distracted, fast, humanizePath, planScroll, planTypeKeystrokes, precise, resolvePersonality } from '@humanjs/core';
+
+// src/index.ts
+
+// src/internal/timing.ts
+function sleep(ms) {
+  return ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
+}
+function speedModeFactor(speed) {
+  switch (speed) {
+    case "fast":
+      return 0.5;
+    case "instant":
+      return 0;
+    default:
+      return 1;
+  }
+}
+function computeDwellTime(meanMs, jitter, personality, speed, rng) {
+  if (meanMs <= 0) return 0;
+  const jitterMag = meanMs * jitter;
+  const offset = rng.nextFloat(-jitterMag, jitterMag);
+  return Math.max(0, (meanMs + offset) * personality.speed * speedModeFactor(speed));
+}
+
+// src/keyboard/index.ts
+async function executeType(target, value, ctx) {
+  const locator = typeof target === "string" ? ctx.page.locator(target) : target;
+  if (value.length === 0) {
+    return { characters: 0, typos: 0, corrections: 0 };
+  }
+  if (ctx.speed === "instant") {
+    await locator.pressSequentially(value, { delay: 0 });
+    return { characters: value.length, typos: 0, corrections: 0 };
+  }
+  await locator.focus();
+  const plan = planTypeKeystrokes(value, ctx.personality.typing, ctx.rng, {
+    personalitySpeed: ctx.personality.speed,
+    speedFactor: speedModeFactor(ctx.speed)
+  });
+  let typos = 0;
+  let corrections = 0;
+  for (const step of plan) {
+    if (step.delayBeforeMs > 0) await sleep(step.delayBeforeMs);
+    await dispatchKey(ctx.page, step.key);
+    if (step.isTypo) typos++;
+    if (step.isCorrection) corrections++;
+  }
+  return { characters: value.length, typos, corrections };
+}
+async function dispatchKey(page, key) {
+  if (key.length > 1 || key.charCodeAt(0) < 128) {
+    await page.keyboard.press(key);
+  } else {
+    await page.keyboard.insertText(key);
+  }
+}
+
+// src/internal/mouse-walk.ts
+async function walkMouseAlongPath(page, path, durationMs) {
+  if (path.length === 0) return;
+  const stepDelayMs = path.length > 1 && durationMs > 0 ? durationMs / (path.length - 1) : 0;
+  for (let i = 0; i < path.length; i++) {
+    const point = path[i];
+    if (!point) continue;
+    await page.mouse.move(point.x, point.y);
+    if (i < path.length - 1 && stepDelayMs > 0) {
+      await sleep(stepDelayMs);
+    }
+  }
+}
+
+// src/mouse/index.ts
+async function executeClick(target, ctx) {
+  const locator = typeof target === "string" ? ctx.page.locator(target) : target;
+  if (ctx.speed === "instant") {
+    const box2 = await locator.boundingBox();
+    await locator.click();
+    const center = box2 ? { x: box2.x + box2.width / 2, y: box2.y + box2.height / 2 } : ctx.getMousePosition();
+    ctx.setMousePosition(center);
+    return { target: center };
+  }
+  const box = await locator.boundingBox();
+  if (!box) {
+    throw new Error(
+      `Cannot click: element not found or has no bounding box (target: ${describeTarget(target)})`
+    );
+  }
+  const targetPoint = pickClickPoint(box, ctx.rng);
+  const startPoint = ctx.getMousePosition();
+  const rawPath = bezierPath(startPoint, targetPoint, ctx.rng, {
+    curvature: ctx.personality.mouse.curvature
+  });
+  const path = humanizePath(rawPath, ctx.rng);
+  const travelMs = computeTravelTime(path, ctx.personality, ctx.speed, ctx.rng);
+  await walkMouseAlongPath(ctx.page, path, travelMs);
+  const preClickMs = computeDwellTime(
+    ctx.personality.dwell.preClickMs,
+    ctx.personality.dwell.preClickJitter,
+    ctx.personality,
+    ctx.speed,
+    ctx.rng
+  );
+  if (preClickMs > 0) await sleep(preClickMs);
+  ctx.setMousePosition(targetPoint);
+  await ctx.page.mouse.click(targetPoint.x, targetPoint.y);
+  const postActionMs = computeDwellTime(
+    ctx.personality.dwell.postActionMs,
+    ctx.personality.dwell.postActionJitter,
+    ctx.personality,
+    ctx.speed,
+    ctx.rng
+  );
+  if (postActionMs > 0) await sleep(postActionMs);
+  return { target: targetPoint };
+}
+function pickClickPoint(box, rng) {
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  const x = clamp(cx + rng.nextGaussian(0, box.width / 8), box.x, box.x + box.width);
+  const y = clamp(cy + rng.nextGaussian(0, box.height / 8), box.y, box.y + box.height);
+  return { x, y };
+}
+function computeTravelTime(path, personality, speed, rng) {
+  let distance = 0;
+  for (let i = 1; i < path.length; i++) {
+    const prev = path[i - 1];
+    const curr = path[i];
+    if (!prev || !curr) continue;
+    distance += Math.hypot(curr.x - prev.x, curr.y - prev.y);
+  }
+  const baseTime = distance / 1e3 * personality.mouse.travelTimeMs;
+  const jitterMag = baseTime * personality.mouse.travelTimeJitter;
+  const jitter = rng.nextFloat(-jitterMag, jitterMag);
+  const total = (baseTime + jitter) * personality.speed * speedModeFactor(speed);
+  return Math.max(0, total);
+}
+function describeTarget(target) {
+  return typeof target === "string" ? target : target.toString?.() ?? "locator";
+}
+function clamp(value, min, max) {
+  return value < min ? min : value > max ? max : value;
+}
+async function executeRead(target, ctx, options = {}) {
+  let words = 0;
+  let locator;
+  if (typeof target === "string") {
+    locator = ctx.page.locator(target);
+  } else if ("words" in target) {
+    words = target.words;
+  } else if ("text" in target) {
+    words = countWords(target.text);
+  } else {
+    locator = target;
+  }
+  let autoDetectedKind;
+  if (locator) {
+    if (options.scrollIntoView) {
+      await locator.scrollIntoViewIfNeeded();
+    }
+    const text = await locator.innerText().catch(() => "");
+    words = countWords(text);
+    if (options.kind === void 0) {
+      autoDetectedKind = await detectKindFromTag(locator);
+    }
+  }
+  const kind = options.kind ?? autoDetectedKind ?? "prose";
+  const durationMs = computeReadingDwellMs(words, ctx.personality.reading, ctx.rng, {
+    kind,
+    wpmMultiplier: options.wpmMultiplier,
+    personalitySpeed: ctx.personality.speed,
+    speedFactor: speedModeFactor(ctx.speed)
+  });
+  if (options.withMotion && locator && durationMs > 0) {
+    const box = await locator.boundingBox().catch(() => null);
+    if (box) {
+      const lineRects = await getLineRects(locator).catch(() => []);
+      const path = planReadingScan(box, ctx.rng, {
+        start: ctx.getMousePosition(),
+        lineRects: lineRects.length > 0 ? lineRects : void 0
+      });
+      await walkMouseAlongPath(ctx.page, path, durationMs);
+      const final = path[path.length - 1];
+      if (final) ctx.setMousePosition(final);
+      return { words, durationMs, kind };
+    }
+  }
+  if (durationMs > 0) await sleep(durationMs);
+  return { words, durationMs, kind };
+}
+async function getLineRects(locator) {
+  const result = await locator.evaluate((el) => {
+    const walker = el.ownerDocument.createTreeWalker(el, 4);
+    const rects = [];
+    let node = walker.nextNode();
+    while (node) {
+      const text = node.textContent ?? "";
+      if (text.trim().length > 0) {
+        const range = el.ownerDocument.createRange();
+        range.selectNodeContents(node);
+        for (const r of Array.from(range.getClientRects())) {
+          if (r.width > 0 && r.height > 0) {
+            rects.push({ x: r.x, y: r.y, width: r.width, height: r.height });
+          }
+        }
+      }
+      node = walker.nextNode();
+    }
+    rects.sort((a, b) => a.y - b.y || a.x - b.x);
+    const merged = [];
+    for (const r of rects) {
+      const last = merged[merged.length - 1];
+      if (last && Math.abs(last.y - r.y) < 1 && r.x - (last.x + last.width) < 6) {
+        const right = Math.max(last.x + last.width, r.x + r.width);
+        const bottom = Math.max(last.y + last.height, r.y + r.height);
+        last.width = right - last.x;
+        last.height = bottom - last.y;
+      } else {
+        merged.push({ ...r });
+      }
+    }
+    return merged;
+  });
+  if (!Array.isArray(result)) return [];
+  return result.filter(
+    (r) => r != null && typeof r === "object" && typeof r.x === "number" && typeof r.y === "number" && typeof r.width === "number" && typeof r.height === "number"
+  );
+}
+async function detectKindFromTag(locator) {
+  const tag = await locator.evaluate((el) => el.tagName?.toLowerCase() ?? "").catch(() => "");
+  if (tag === "pre" || tag === "code") return "code";
+  return void 0;
+}
+var RESERVED_TARGETS = /* @__PURE__ */ new Set(["natural", "end", "top"]);
+async function executeScroll(target, ctx, options = {}) {
+  const { page, personality, rng, speed } = ctx;
+  const speedFactor = speedModeFactor(speed);
+  const axis = options.axis ?? "y";
+  const container = resolveWithin(options.within, ctx);
+  const geom = container ? await readContainerGeometry(container, axis) : await readWindowGeometry(page, axis);
+  if (!geom) {
+    return { from: 0, to: 0, distance: 0, durationMs: 0 };
+  }
+  const from = geom.current;
+  const targetPos = await resolveTarget(target, ctx, geom, container, axis, options.block);
+  const to = clamp2(targetPos, 0, Math.max(0, geom.total - geom.viewport));
+  const distance = to - from;
+  if (distance === 0) {
+    return { from, to, distance: 0, durationMs: 0 };
+  }
+  if (speed === "instant") {
+    if (container) {
+      await container.evaluate(
+        (el, args) => {
+          const a = args;
+          if (a.axis === "x") el.scrollTo(a.pos, el.scrollTop);
+          else el.scrollTo(el.scrollLeft, a.pos);
+        },
+        { axis, pos: to }
+      );
+    } else {
+      await page.evaluate(
+        (args) => {
+          if (args.axis === "x") window.scrollTo(args.pos, window.scrollY);
+          else window.scrollTo(window.scrollX, args.pos);
+        },
+        { axis, pos: to }
+      );
+    }
+    return { from, to, distance, durationMs: 0 };
+  }
+  const segments = planScroll(from, to, personality.scroll, rng, {
+    forceOvershoot: options.overshoot,
+    withPauses: options.withPauses,
+    personalitySpeed: personality.speed,
+    speedFactor
+  });
+  if (container && geom.hover) {
+    await page.mouse.move(geom.hover.x, geom.hover.y);
+  }
+  const startedAt = Date.now();
+  await walkSegments(page, segments, axis, container);
+  const durationMs = Date.now() - startedAt;
+  return { from, to, distance, durationMs };
+}
+function resolveWithin(within, ctx) {
+  if (!within) return null;
+  return typeof within === "string" ? ctx.page.locator(within) : within;
+}
+async function readWindowGeometry(page, axis) {
+  const g = await page.evaluate((a) => {
+    if (a === "x") {
+      return {
+        current: window.scrollX,
+        viewport: window.innerWidth,
+        total: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0)
+      };
+    }
+    return {
+      current: window.scrollY,
+      viewport: window.innerHeight,
+      total: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0)
+    };
+  }, axis);
+  return { current: g.current, viewport: g.viewport, total: g.total };
+}
+async function readContainerGeometry(container, axis) {
+  return container.evaluate((el, a) => {
+    const rect = el.getBoundingClientRect();
+    const isX = a === "x";
+    return {
+      current: isX ? el.scrollLeft : el.scrollTop,
+      viewport: isX ? el.clientWidth : el.clientHeight,
+      total: isX ? el.scrollWidth : el.scrollHeight,
+      hover: {
+        x: rect.left + rect.width / 2,
+        y: rect.top + rect.height / 2
+      }
+    };
+  }, axis).catch(() => null);
+}
+async function resolveTarget(target, ctx, geom, container, axis, block = "start") {
+  if (target === void 0 || target === "natural") return geom.current + geom.viewport;
+  if (target === "end") return geom.total;
+  if (target === "top") return 0;
+  if (typeof target === "object" && "by" in target) return geom.current + target.by;
+  if (typeof target === "object" && "to" in target) return target.to;
+  const elementLocator = typeof target === "string" && !RESERVED_TARGETS.has(target) ? ctx.page.locator(target) : typeof target === "string" ? null : target;
+  if (!elementLocator) return geom.current + geom.viewport;
+  return container ? resolveElementWithinContainer(elementLocator, container, geom, axis, block) : resolveElementInWindow(elementLocator, geom, axis, block);
+}
+async function resolveElementInWindow(elementLocator, geom, axis, block) {
+  const rect = await elementLocator.boundingBox().catch(() => null);
+  if (!rect) return geom.current;
+  const relStart = axis === "x" ? rect.x : rect.y;
+  const length = axis === "x" ? rect.width : rect.height;
+  const absoluteStart = geom.current + relStart;
+  const absoluteEnd = absoluteStart + length;
+  if (block === "start") return absoluteStart;
+  if (block === "end") return absoluteEnd - geom.viewport;
+  if (block === "nearest") {
+    if (relStart >= 0 && relStart + length <= geom.viewport) return geom.current;
+    if (relStart < 0) return absoluteStart;
+    return absoluteEnd - geom.viewport;
+  }
+  return absoluteStart - (geom.viewport - length) / 2;
+}
+async function resolveElementWithinContainer(elementLocator, container, geom, axis, block) {
+  const rects = await container.evaluate(
+    (containerEl, args) => {
+      const elementEl = args.sel ? document.querySelector(args.sel) : null;
+      const targetEl = elementEl ?? containerEl.querySelector(":scope > *");
+      if (!targetEl) return null;
+      const cRect = containerEl.getBoundingClientRect();
+      const eRect = targetEl.getBoundingClientRect();
+      return args.axis === "x" ? { relStart: eRect.left - cRect.left, length: eRect.width } : { relStart: eRect.top - cRect.top, length: eRect.height };
+    },
+    { sel: await locatorSelector(elementLocator), axis }
+  ).catch(() => null);
+  if (!rects) return geom.current;
+  const offsetStart = rects.relStart + geom.current;
+  const offsetEnd = offsetStart + rects.length;
+  if (block === "start") return offsetStart;
+  if (block === "end") return offsetEnd - geom.viewport;
+  if (block === "nearest") {
+    if (rects.relStart >= 0 && rects.relStart + rects.length <= geom.viewport) {
+      return geom.current;
+    }
+    if (rects.relStart < 0) return offsetStart;
+    return offsetEnd - geom.viewport;
+  }
+  return offsetStart - (geom.viewport - rects.length) / 2;
+}
+async function locatorSelector(locator) {
+  const s = locator.toString?.();
+  if (typeof s !== "string") return null;
+  const match = /locator\(['"](.+?)['"]/.exec(s);
+  if (!match) return null;
+  const raw = match[1] ?? "";
+  const eq = raw.indexOf("=");
+  return eq > 0 && /^[a-z]+$/.test(raw.slice(0, eq)) ? raw.slice(eq + 1) : raw;
+}
+async function walkSegments(page, segments, axis, container) {
+  for (const segment of segments) {
+    if (segment.delayBeforeMs > 0) await sleep(segment.delayBeforeMs);
+    if (segment.delta === 0) continue;
+    if (container) {
+      await container.evaluate(
+        (el, args) => {
+          const a = args;
+          if (a.axis === "x") el.scrollLeft += a.delta;
+          else el.scrollTop += a.delta;
+        },
+        { axis, delta: segment.delta }
+      );
+    } else if (axis === "x") {
+      await page.mouse.wheel(segment.delta, 0);
+    } else {
+      await page.mouse.wheel(0, segment.delta);
+    }
+  }
+}
+function clamp2(value, min, max) {
+  return value < min ? min : value > max ? max : value;
+}
+
+// src/mouse-helper/index.ts
+var CURSOR_PATH = "M 0 0 L 16 6 L 8 9.5 L 5 19 Z";
+async function installMouseHelper(target, options = {}) {
+  const config = {
+    color: options.color ?? "#f5a55c",
+    stroke: "#020203",
+    size: options.size ?? 22,
+    showClicks: options.showClicks ?? true,
+    haloOpacity: options.haloOpacity ?? 0.18,
+    path: CURSOR_PATH
+  };
+  await target.addInitScript(installScript, config);
+  const pages = "pages" in target ? target.pages() : [target];
+  await Promise.all(
+    pages.map((page) => page.evaluate(installScript, config).catch(() => void 0))
+  );
+}
+function installScript(config) {
+  const guardKey = "__humanjsMouseHelperInstalled";
+  const w = window;
+  if (w[guardKey]) return;
+  w[guardKey] = true;
+  const attach = () => {
+    const cursor = document.createElement("div");
+    cursor.setAttribute("aria-hidden", "true");
+    cursor.setAttribute("data-humanjs-cursor", "true");
+    cursor.style.cssText = [
+      "position: fixed",
+      "left: 0",
+      "top: 0",
+      `width: ${config.size}px`,
+      `height: ${config.size + 4}px`,
+      "pointer-events: none",
+      "z-index: 2147483647",
+      // Start visible at (0, 0) so the cursor is on screen from the moment
+      // the page loads — without this the helper looks like nothing happened
+      // until the first mousemove arrives.
+      "opacity: 1",
+      "transform: translate(0px, 0px)",
+      // CSS interpolates between successive `mousemove` updates so the
+      // cursor reads as continuous motion instead of discrete hops. Slightly
+      // longer than the path-walker's typical step interval (~30–80ms) so
+      // each tween is still settling when the next move lands → no pauses.
+      "transition: transform 110ms ease-out, opacity 0.18s ease-out",
+      "will-change: transform"
+    ].join("; ");
+    const haloRadius = Math.round(config.size * 0.6);
+    cursor.innerHTML = `
+      <svg width="${config.size}" height="${config.size + 4}" viewBox="0 0 22 24" style="overflow: visible;">
+        <circle cx="0" cy="0" r="${haloRadius}" fill="${config.color}" opacity="${config.haloOpacity}" />
+        <path d="${config.path}" fill="${config.color}" stroke="${config.stroke}" stroke-width="0.7" stroke-linejoin="round" />
+      </svg>
+    `;
+    document.body.appendChild(cursor);
+    let lastX = 0;
+    let lastY = 0;
+    const onMove = (e) => {
+      lastX = e.clientX;
+      lastY = e.clientY;
+      cursor.style.transform = `translate(${lastX}px, ${lastY}px)`;
+      cursor.style.opacity = "1";
+    };
+    window.addEventListener("mousemove", onMove, { capture: true, passive: true });
+    document.addEventListener("mousemove", onMove, { capture: true, passive: true });
+    document.addEventListener(
+      "mouseleave",
+      () => {
+        cursor.style.opacity = "0";
+      },
+      { capture: true, passive: true }
+    );
+    if (config.showClicks) {
+      const styleEl = document.createElement("style");
+      styleEl.textContent = "@keyframes humanjs-ripple { 0% { transform: translate(-50%, -50%) scale(0.4); opacity: 0.9; } 100% { transform: translate(-50%, -50%) scale(2); opacity: 0; } }";
+      document.head.appendChild(styleEl);
+      window.addEventListener(
+        "mousedown",
+        () => {
+          const ripple = document.createElement("div");
+          ripple.style.cssText = [
+            "position: fixed",
+            `left: ${lastX}px`,
+            `top: ${lastY}px`,
+            "width: 28px",
+            "height: 28px",
+            "border-radius: 50%",
+            `border: 1.5px solid ${config.color}`,
+            "pointer-events: none",
+            "z-index: 2147483646",
+            "animation: humanjs-ripple 0.45s ease-out forwards"
+          ].join("; ");
+          document.body.appendChild(ripple);
+          window.setTimeout(() => ripple.remove(), 500);
+        },
+        { capture: true, passive: true }
+      );
+    }
+  };
+  if (document.body) attach();
+  else document.addEventListener("DOMContentLoaded", attach, { once: true });
+}
 
 // src/index.ts
 async function createHuman(page, options = {}) {
@@ -33,6 +539,7 @@ async function createHuman(page, options = {}) {
       throw error;
     }
   }
+  let lastMousePosition = options.initialMousePosition ?? { x: 0, y: 0 };
   return {
     personality,
     speed,
@@ -40,10 +547,88 @@ async function createHuman(page, options = {}) {
       await performAction({ type: "goto", params: { url } }, async () => {
         await page.goto(url);
       });
+    },
+    async click(target) {
+      const description = typeof target === "string" ? target : target.toString?.() ?? "locator";
+      await performAction({ type: "click", params: { target: description } }, async () => {
+        await executeClick(target, {
+          page,
+          personality,
+          rng,
+          speed,
+          getMousePosition: () => lastMousePosition,
+          setMousePosition: (point) => {
+            lastMousePosition = point;
+          }
+        });
+      });
+    },
+    async type(target, value) {
+      const description = typeof target === "string" ? target : target.toString?.() ?? "locator";
+      await performAction(
+        { type: "type", params: { target: description, length: value.length } },
+        async () => {
+          await executeType(target, value, { page, personality, rng, speed });
+        }
+      );
+    },
+    async read(target, options2) {
+      const description = describeReadTarget(target);
+      return performAction(
+        {
+          type: "read",
+          params: {
+            target: description,
+            kind: options2?.kind
+          }
+        },
+        () => executeRead(
+          target,
+          {
+            page,
+            personality,
+            rng,
+            speed,
+            // Read shares the session's tracked cursor position so an eye
+            // scan starts from where the last click left off, and the next
+            // click starts from where the scan ended.
+            getMousePosition: () => lastMousePosition,
+            setMousePosition: (point) => {
+              lastMousePosition = point;
+            }
+          },
+          options2
+        )
+      );
+    },
+    async scroll(target, options2) {
+      const description = describeScrollTarget(target);
+      return performAction(
+        {
+          type: "scroll",
+          params: { target: description }
+        },
+        () => executeScroll(target, { page, personality, rng, speed }, options2)
+      );
     }
   };
 }
+function describeScrollTarget(target) {
+  if (target === void 0) return "natural";
+  if (typeof target === "string") return target;
+  if ("by" in target) return `by:${target.by}`;
+  if ("to" in target) return `to:${target.to}`;
+  return target.toString?.() ?? "locator";
+}
+function describeReadTarget(target) {
+  if (typeof target === "string") return target;
+  if ("words" in target && typeof target.words === "number") return `${target.words} words`;
+  if ("text" in target && typeof target.text === "string") {
+    return `text:${target.text.length} chars`;
+  }
+  return target.toString?.() ?? "locator";
+}
 
-export { createHuman };
+export { createHuman, installMouseHelper };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map