@humanjs/playwright 0.4.0 → 0.6.0

package/dist/index.js

@@ -63,6 +63,73 @@ async function dispatchKey(page, key) {
     await page.keyboard.insertText(key);
   }
 }
+async function executePaste(target, value, ctx) {
+  if (value.length === 0) return { characters: 0 };
+  const locator = typeof target === "string" ? ctx.page.locator(target) : target;
+  await locator.focus();
+  await ctx.page.keyboard.insertText(value);
+  return { characters: value.length };
+}
+async function executePress(key, ctx) {
+  const dispatched = resolveChord(key);
+  await ctx.page.keyboard.press(dispatched);
+  return { dispatched };
+}
+function resolveChord(key) {
+  const parts = key.split("+").map((p) => p.trim()).filter((p) => p.length > 0);
+  if (parts.length === 0) {
+    throw new Error(`Invalid key: ${JSON.stringify(key)} \u2014 empty or only separators`);
+  }
+  const keyToken = parts[parts.length - 1];
+  if (keyToken === void 0) {
+    throw new Error(`Invalid key: ${JSON.stringify(key)} \u2014 missing key`);
+  }
+  const modifierTokens = parts.slice(0, -1);
+  const modifiers = [];
+  for (const token of modifierTokens) {
+    const resolved = resolveModifier(token);
+    if (resolved === null) {
+      throw new Error(
+        `Invalid key modifier: ${JSON.stringify(token)} in ${JSON.stringify(key)}. Use one of: Mod/CmdOrCtrl/CommandOrControl, Cmd/Command/Meta/Win/Super, Ctrl/Control, Alt/Option/Opt, Shift.`
+      );
+    }
+    modifiers.push(resolved);
+  }
+  return [...modifiers, normalizeKey(keyToken)].join("+");
+}
+function resolveModifier(token) {
+  const lower = token.toLowerCase();
+  switch (lower) {
+    case "mod":
+    case "cmdorctrl":
+    case "commandorcontrol":
+      return isMac() ? "Meta" : "Control";
+    case "cmd":
+    case "command":
+    case "meta":
+    case "win":
+    case "super":
+      return "Meta";
+    case "ctrl":
+    case "control":
+      return "Control";
+    case "alt":
+    case "option":
+    case "opt":
+      return "Alt";
+    case "shift":
+      return "Shift";
+    default:
+      return null;
+  }
+}
+function normalizeKey(key) {
+  if (key.length === 1) return key.toUpperCase();
+  return key.charAt(0).toUpperCase() + key.slice(1);
+}
+function isMac() {
+  return process.platform === "darwin";
+}
 
 // src/internal/mouse-walk.ts
 async function walkMouseAlongPath(page, path, durationMs) {
@@ -77,31 +144,198 @@ async function walkMouseAlongPath(page, path, durationMs) {
     }
   }
 }
+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 = clamp(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 clamp(value, min, max) {
+  return value < min ? min : value > max ? max : value;
+}
 
 // src/mouse/index.ts
-async function executeClick(target, ctx) {
-  const locator = typeof target === "string" ? ctx.page.locator(target) : target;
+async function executeClick(target, ctx, options = {}) {
+  const button = options.button ?? "left";
   if (ctx.speed === "instant") {
+    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();
+    await locator.click({ button });
     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 { 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,
@@ -111,7 +345,7 @@ async function executeClick(target, ctx) {
   );
   if (preClickMs > 0) await sleep(preClickMs);
   ctx.setMousePosition(targetPoint);
-  await ctx.page.mouse.click(targetPoint.x, targetPoint.y);
+  await ctx.page.mouse.click(targetPoint.x, targetPoint.y, { button });
   const postActionMs = computeDwellTime(
     ctx.personality.dwell.postActionMs,
     ctx.personality.dwell.postActionJitter,
@@ -122,11 +356,248 @@ async function executeClick(target, ctx) {
   if (postActionMs > 0) await sleep(postActionMs);
   return { target: targetPoint };
 }
-function pickClickPoint(box, rng) {
+async function executeHover(target, ctx) {
+  if (ctx.speed === "instant") {
+    const box = await readBoxWithAutoScroll(target, ctx, "hover");
+    const center = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+    await ctx.page.mouse.move(center.x, center.y);
+    ctx.setMousePosition(center);
+    return { target: center };
+  }
+  const targetPoint = await moveToTarget(target, ctx);
+  const dwellMs = computeDwellTime(
+    ctx.personality.dwell.preClickMs,
+    ctx.personality.dwell.preClickJitter,
+    ctx.personality,
+    ctx.speed,
+    ctx.rng
+  );
+  if (dwellMs > 0) await sleep(dwellMs);
+  ctx.setMousePosition(targetPoint);
+  return { target: targetPoint };
+}
+async function executeDrag(from, to, ctx) {
+  const scrollYBeforeResolve = await readScrollY(ctx.page);
+  let { point: fromPoint, box: fromBox } = await resolveTargetPointAndBox(from, ctx, "drag");
+  let { point: toPoint, box: toBox } = await resolveTargetPointAndBox(to, ctx, "drag");
+  const resolveScrollDelta = await readScrollY(ctx.page) - scrollYBeforeResolve;
+  if (resolveScrollDelta !== 0) {
+    if (isPoint(from)) fromPoint = { x: fromPoint.x, y: fromPoint.y - resolveScrollDelta };
+    if (isPoint(to)) toPoint = { x: toPoint.x, y: toPoint.y - resolveScrollDelta };
+  }
+  if (ctx.speed === "instant") {
+    await ctx.page.mouse.move(fromPoint.x, fromPoint.y);
+    await ctx.page.mouse.down();
+    await ctx.page.mouse.move(toPoint.x, toPoint.y);
+    await ctx.page.mouse.up();
+    ctx.setMousePosition(toPoint);
+    return { from: fromPoint, to: toPoint };
+  }
+  if (fromBox && toBox) {
+    const scrollDelta = computeCurveScrollDelta(
+      fromPoint,
+      toPoint,
+      ctx.page.viewportSize(),
+      ctx.personality.mouse.curvature
+    );
+    if (scrollDelta !== 0) {
+      await executeScroll({ by: scrollDelta }, ctx, {});
+      const refreshedFrom = await resolveTargetPointAndBox(from, ctx, "drag");
+      fromPoint = refreshedFrom.point;
+      fromBox = refreshedFrom.box;
+      const refreshedTo = await resolveTargetPointAndBox(to, ctx, "drag");
+      toPoint = refreshedTo.point;
+      toBox = refreshedTo.box;
+    }
+  }
+  await maybeMisclickBeat(ctx, fromBox, fromPoint);
+  await walkBezierTo(fromPoint, ctx);
+  ctx.setMousePosition(fromPoint);
+  const preDragMs = computeDwellTime(
+    ctx.personality.dwell.preClickMs,
+    ctx.personality.dwell.preClickJitter,
+    ctx.personality,
+    ctx.speed,
+    ctx.rng
+  );
+  if (preDragMs > 0) await sleep(preDragMs);
+  await ctx.page.mouse.down();
+  await maybeMisclickBeat(ctx, toBox, toPoint);
+  await walkBezierTo(toPoint, ctx);
+  await ctx.page.mouse.up();
+  ctx.setMousePosition(toPoint);
+  const postActionMs = computeDwellTime(
+    ctx.personality.dwell.postActionMs,
+    ctx.personality.dwell.postActionJitter,
+    ctx.personality,
+    ctx.speed,
+    ctx.rng
+  );
+  if (postActionMs > 0) await sleep(postActionMs);
+  return { from: fromPoint, to: toPoint };
+}
+async function executeMove(target, ctx) {
+  const point = await resolveTargetPoint(target, ctx, "move");
+  if (ctx.speed === "instant") {
+    await ctx.page.mouse.move(point.x, point.y);
+    ctx.setMousePosition(point);
+    return { target: point };
+  }
+  await walkBezierTo(point, ctx);
+  ctx.setMousePosition(point);
+  return { target: point };
+}
+async function moveToTarget(target, ctx) {
+  const box = await readBoxWithAutoScroll(target, ctx, "hover");
+  const targetPoint = pickClickPoint(box, ctx.rng, ctx.personality.mouse.clickSpread);
+  await walkBezierTo(targetPoint, ctx);
+  return targetPoint;
+}
+async function walkBezierTo(to, ctx) {
+  const startPoint = ctx.getMousePosition();
+  const rawPath = bezierPath(startPoint, to, 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);
+}
+async function resolveTargetPoint(target, ctx, action) {
+  if (isPoint(target)) return target;
+  return resolveLocatorPoint(target, ctx, action);
+}
+async function resolveTargetPointAndBox(target, ctx, action) {
+  if (isPoint(target)) return { point: target, box: null };
+  const box = await readBoxWithAutoScroll(target, ctx, action);
+  const point = pickClickPoint(box, ctx.rng, ctx.personality.mouse.clickSpread);
+  return { point, box };
+}
+async function resolveLocatorPoint(target, ctx, action) {
+  const box = await readBoxWithAutoScroll(target, ctx, action);
+  return pickClickPoint(box, ctx.rng, ctx.personality.mouse.clickSpread);
+}
+async function readBoxWithAutoScroll(target, ctx, action) {
+  const locator = typeof target === "string" ? ctx.page.locator(target) : target;
+  let box = await locator.boundingBox();
+  if (!box) {
+    throw new Error(
+      `Cannot ${action}: element not found or has no bounding box (target: ${describeTarget(target)})`
+    );
+  }
+  const viewport = ctx.page.viewportSize();
+  if (viewport && !isBoxCenterInViewport(box, viewport)) {
+    if (ctx.speed === "instant") {
+      await locator.scrollIntoViewIfNeeded();
+    } else {
+      await executeScroll(locator, ctx, { block: "center" });
+    }
+    box = await locator.boundingBox();
+    if (!box) {
+      throw new Error(
+        `Cannot ${action}: element disappeared after scrolling into view (target: ${describeTarget(target)})`
+      );
+    }
+  }
+  return box;
+}
+function isBoxCenterInViewport(box, viewport) {
+  const cx = box.x + box.width / 2;
+  const cy = box.y + box.height / 2;
+  return cx >= 0 && cx <= viewport.width && cy >= 0 && cy <= viewport.height;
+}
+async function readScrollY(page) {
+  if (typeof page.evaluate !== "function") return 0;
+  return page.evaluate(() => window.scrollY);
+}
+var CURVE_VIEWPORT_MARGIN = 20;
+function computeCurveScrollDelta(from, to, viewport, curvature) {
+  if (!viewport) return 0;
+  const distance = Math.hypot(to.x - from.x, to.y - from.y);
+  const perpendicularExtent = distance * curvature;
+  const minY = Math.min(from.y, to.y) - perpendicularExtent;
+  const maxY = Math.max(from.y, to.y) + perpendicularExtent;
+  const topOverflow = -minY + CURVE_VIEWPORT_MARGIN;
+  const bottomOverflow = maxY + CURVE_VIEWPORT_MARGIN - viewport.height;
+  if (bottomOverflow > 0 && bottomOverflow >= topOverflow) return bottomOverflow;
+  if (topOverflow > 0) return -topOverflow;
+  return 0;
+}
+function isPoint(target) {
+  return typeof target === "object" && target !== null && !("boundingBox" in target) && typeof target.x === "number" && typeof target.y === "number";
+}
+var MISCLICK_OFFSET_MIN = 5;
+var MISCLICK_OFFSET_MAX = 15;
+async function maybeMisclickBeat(ctx, box, targetPoint) {
+  if (!ctx.rng.chance(ctx.personality.mouse.misclickProbability)) return;
+  if (cursorAlreadyOnTarget(ctx.getMousePosition(), box, targetPoint)) return;
+  const viewport = ctx.page.viewportSize();
+  const misclickPoint = box ? pickMisclickOutsideBox(box, ctx.rng, viewport) : pickMisclickAroundPoint(targetPoint, ctx.rng, viewport);
+  if (misclickPoint === null) return;
+  await walkBezierTo(misclickPoint, ctx);
+  ctx.setMousePosition(misclickPoint);
+  const realizeMs = computeDwellTime(
+    ctx.personality.dwell.preClickMs,
+    ctx.personality.dwell.preClickJitter,
+    ctx.personality,
+    ctx.speed,
+    ctx.rng
+  );
+  if (realizeMs > 0) await sleep(realizeMs);
+}
+function cursorAlreadyOnTarget(current, box, targetPoint) {
+  if (box) {
+    return current.x >= box.x && current.x <= box.x + box.width && current.y >= box.y && current.y <= box.y + box.height;
+  }
+  const dx = current.x - targetPoint.x;
+  const dy = current.y - targetPoint.y;
+  return Math.hypot(dx, dy) < MISCLICK_OFFSET_MIN;
+}
+function pickMisclickOutsideBox(box, rng, viewport) {
+  const edge = rng.nextInt(0, 4);
+  const offset = rng.nextFloat(MISCLICK_OFFSET_MIN, MISCLICK_OFFSET_MAX);
+  const along = rng.nextFloat(0.2, 0.8);
+  let x;
+  let y;
+  if (edge === 0) {
+    x = box.x + box.width * along;
+    y = box.y - offset;
+  } else if (edge === 1) {
+    x = box.x + box.width + offset;
+    y = box.y + box.height * along;
+  } else if (edge === 2) {
+    x = box.x + box.width * along;
+    y = box.y + box.height + offset;
+  } else {
+    x = box.x - offset;
+    y = box.y + box.height * along;
+  }
+  if (viewport) {
+    x = clamp2(x, 0, viewport.width - 1);
+    y = clamp2(y, 0, viewport.height - 1);
+  }
+  const insideBox = x >= box.x && x <= box.x + box.width && y >= box.y && y <= box.y + box.height;
+  if (insideBox) return null;
+  return { x, y };
+}
+function pickMisclickAroundPoint(target, rng, viewport) {
+  const angle = rng.nextFloat(0, Math.PI * 2);
+  const distance = rng.nextFloat(MISCLICK_OFFSET_MIN, MISCLICK_OFFSET_MAX);
+  let x = target.x + Math.cos(angle) * distance;
+  let y = target.y + Math.sin(angle) * distance;
+  if (viewport) {
+    x = clamp2(x, 0, viewport.width - 1);
+    y = clamp2(y, 0, viewport.height - 1);
+  }
+  if (x === target.x && y === target.y) return null;
+  return { x, y };
+}
+function pickClickPoint(box, rng, clickSpread) {
   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);
+  const sigmaX = box.width * clickSpread;
+  const sigmaY = box.height * clickSpread;
+  const x = clamp2(cx + rng.nextGaussian(0, sigmaX), box.x, box.x + box.width);
+  const y = clamp2(cy + rng.nextGaussian(0, sigmaY), box.y, box.y + box.height);
   return { x, y };
 }
 function computeTravelTime(path, personality, speed, rng) {
@@ -144,9 +615,10 @@ function computeTravelTime(path, personality, speed, rng) {
   return Math.max(0, total);
 }
 function describeTarget(target) {
+  if (isPoint(target)) return `point(${target.x}, ${target.y})`;
   return typeof target === "string" ? target : target.toString?.() ?? "locator";
 }
-function clamp(value, min, max) {
+function clamp2(value, min, max) {
   return value < min ? min : value > max ? max : value;
 }
 async function executeRead(target, ctx, options = {}) {
@@ -630,178 +1102,6 @@ async function startCapture(page, options = {}) {
     }
   };
 }
-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";
@@ -966,6 +1266,23 @@ async function createHuman(page, options = {}) {
     }
   }
   let lastMousePosition = options.initialMousePosition ?? { x: 0, y: 0 };
+  const mouseCtx = () => ({
+    page,
+    personality,
+    rng,
+    speed,
+    getMousePosition: () => lastMousePosition,
+    setMousePosition: (point) => {
+      lastMousePosition = point;
+    }
+  });
+  const describeMouseTarget = (target) => {
+    if (typeof target === "string") return target;
+    if ("x" in target && "y" in target && typeof target.x === "number") {
+      return `point(${target.x}, ${target.y})`;
+    }
+    return target.toString?.() ?? "locator";
+  };
   return {
     personality,
     speed,
@@ -975,29 +1292,65 @@ async function createHuman(page, options = {}) {
       });
     },
     async click(target) {
-      const description = typeof target === "string" ? target : target.toString?.() ?? "locator";
+      const description = describeMouseTarget(target);
       await performAction({ type: "click", params: { target: description } }, async () => {
-        await executeClick(target, {
-          page,
-          personality,
-          rng,
-          speed,
-          getMousePosition: () => lastMousePosition,
-          setMousePosition: (point) => {
-            lastMousePosition = point;
-          }
-        });
+        await executeClick(target, mouseCtx());
+      });
+    },
+    async rightClick(target) {
+      const description = describeMouseTarget(target);
+      await performAction({ type: "rightClick", params: { target: description } }, async () => {
+        await executeClick(target, mouseCtx(), { button: "right" });
+      });
+    },
+    async hover(target) {
+      const description = describeMouseTarget(target);
+      await performAction({ type: "hover", params: { target: description } }, async () => {
+        await executeHover(target, mouseCtx());
+      });
+    },
+    async move(target) {
+      const description = describeMouseTarget(target);
+      await performAction({ type: "move", params: { target: description } }, async () => {
+        await executeMove(target, mouseCtx());
+      });
+    },
+    async drag(from, to) {
+      const fromDesc = describeMouseTarget(from);
+      const toDesc = describeMouseTarget(to);
+      await performAction({ type: "drag", params: { from: fromDesc, to: toDesc } }, async () => {
+        await executeDrag(from, to, mouseCtx());
       });
     },
     async type(target, value) {
-      const description = typeof target === "string" ? target : target.toString?.() ?? "locator";
+      const description = describeMouseTarget(target);
       await performAction(
         { type: "type", params: { target: description, length: value.length } },
         async () => {
+          if (speed !== "instant" && value.length > 0) {
+            await executeClick(target, mouseCtx());
+          }
           await executeType(target, value, { page, personality, rng, speed });
         }
       );
     },
+    async paste(target, value) {
+      const description = describeMouseTarget(target);
+      await performAction(
+        { type: "paste", params: { target: description, length: value.length } },
+        async () => {
+          if (speed !== "instant" && value.length > 0) {
+            await executeClick(target, mouseCtx());
+          }
+          await executePaste(target, value, { page, personality, rng, speed });
+        }
+      );
+    },
+    async press(key) {
+      await performAction({ type: "press", params: { key } }, async () => {
+        await executePress(key, { page, personality, rng, speed });
+      });
+    },
     async read(target, options2) {
       const description = describeReadTarget(target);
       return performAction(
@@ -1081,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);
     }
   };
 }