@humanjs/playwright 0.7.0 → 0.8.0

package/dist/index.js

@@ -1,1761 +1,3 @@
-import { resolvePersonality, createRng, sleep as sleep$1, 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, sleep } from '@humanjs/core';
-import { spawn } from 'child_process';
-import { rmSync } from 'fs';
-import { mkdir, writeFile, mkdtemp, rm } from 'fs/promises';
-import { dirname, extname, join } from 'path';
-import ffmpegStatic from 'ffmpeg-static';
-import { tmpdir } from 'os';
-export { chromium, firefox, webkit } from 'playwright';
-
-// 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);
-  }
-}
-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) {
-  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);
-    }
-  }
-}
-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, 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({ 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 { 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,
-    ctx.personality,
-    ctx.speed,
-    ctx.rng
-  );
-  if (preClickMs > 0) await sleep(preClickMs);
-  ctx.setMousePosition(targetPoint);
-  await ctx.page.mouse.click(targetPoint.x, targetPoint.y, { button });
-  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 };
-}
-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 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) {
-  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) {
-  if (isPoint(target)) return `point(${target.x}, ${target.y})`;
-  return typeof target === "string" ? target : target.toString?.() ?? "locator";
-}
-function clamp2(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)
-  });
-  const withMotion = options.withMotion ?? true;
-  if (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;
-}
-
-// src/recording/codegen.ts
-var POINT_RE = /^point\((-?\d+(?:\.\d+)?),\s*(-?\d+(?:\.\d+)?)\)$/;
-var POINT_COMMENT = " // raw coordinate \u2014 replace with a locator for a stable selector";
-var UNCAPTURED_COMMENT = " // input not captured (masked or captureInputs disabled) \u2014 fill in (e.g. process.env.X)";
-function q(value) {
-  return `'${String(value ?? "").replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r")}'`;
-}
-function targetArg(desc) {
-  const s = String(desc ?? "");
-  const m = s.match(POINT_RE);
-  if (m) return { code: `{ x: ${m[1]}, y: ${m[2]} }`, isPoint: true };
-  return { code: q(s), isPoint: false };
-}
-function createHumanOptions(timeline, ciSpeed = false) {
-  const parts = [`    personality: ${q(timeline.personality)},`];
-  if (timeline.seed !== null) parts.push(`    seed: ${q(timeline.seed)},`);
-  parts.push(
-    ciSpeed ? `    speed: process.env.CI ? 'instant' : ${q(timeline.speed)},` : `    speed: ${q(timeline.speed)},`
-  );
-  return `{
-${parts.join("\n")}
-  }`;
-}
-function emitScroll(target) {
-  const s = String(target ?? "natural");
-  if (s === "natural") return "  await human.scroll('natural');";
-  const by = s.match(/^by:(-?\d+(?:\.\d+)?)$/);
-  if (by) return `  await human.scroll({ by: ${by[1]} });`;
-  const to = s.match(/^to:(-?\d+(?:\.\d+)?)$/);
-  if (to) return `  await human.scroll({ to: ${to[1]} });`;
-  return `  await human.scroll(${q(s)});`;
-}
-function emitAction(e, opts = {}) {
-  const p = e.params;
-  switch (e.type) {
-    case "goto": {
-      const url = String(p.url ?? "");
-      if (opts.baseOrigin && url.startsWith(opts.baseOrigin)) {
-        return `  await human.goto(${q(url.slice(opts.baseOrigin.length) || "/")});`;
-      }
-      return `  await human.goto(${q(url)});`;
-    }
-    case "click":
-    case "rightClick":
-    case "hover":
-    case "move": {
-      const { code, isPoint: isPoint2 } = targetArg(p.target);
-      return `  await human.${e.type}(${code});${isPoint2 ? POINT_COMMENT : ""}`;
-    }
-    case "drag": {
-      const from = targetArg(p.from);
-      const to = targetArg(p.to);
-      const comment = from.isPoint || to.isPoint ? POINT_COMMENT : "";
-      return `  await human.drag(${from.code}, ${to.code});${comment}`;
-    }
-    case "type":
-    case "paste": {
-      const { code, isPoint: isPoint2 } = targetArg(p.target);
-      if (e.inputValue === void 0) {
-        return `  await human.${e.type}(${code}, '');${UNCAPTURED_COMMENT}`;
-      }
-      const call = `  await human.${e.type}(${code}, ${q(e.inputValue)});`;
-      if (opts.asserts && !isPoint2) {
-        return `${call}
-  await expect(page.locator(${code})).toHaveValue(${q(e.inputValue)});`;
-      }
-      return call;
-    }
-    case "press":
-      return `  await human.press(${q(p.key)});`;
-    case "scroll":
-      return emitScroll(p.target);
-    case "read": {
-      const desc = String(p.target ?? "");
-      if (/^\d+ words$/.test(desc) || /^text:\d+ chars$/.test(desc)) {
-        return `  // human.read(...) \u2014 ${desc}; original target not captured`;
-      }
-      const call = `  await human.read(${q(desc)});`;
-      if (opts.asserts) return `${call}
-  await expect(page.locator(${q(desc)})).toBeVisible();`;
-      return call;
-    }
-    case "sleep":
-      return `  await sleep(${Number(p.ms) || 0});`;
-    case "reload":
-      return "  await human.reload();";
-    case "goBack":
-      return "  await human.goBack();";
-    case "goForward":
-      return "  await human.goForward();";
-    default:
-      return `  // unsupported action: ${e.type}`;
-  }
-}
-function needsSleepImport(timeline) {
-  return timeline.events.some((e) => e.type === "sleep");
-}
-function generateHumanJS(timeline) {
-  const imports = needsSleepImport(timeline) ? "import { chromium, createHuman, sleep } from '@humanjs/playwright';" : "import { chromium, createHuman } from '@humanjs/playwright';";
-  const body = timeline.events.map((e) => emitAction(e)).join("\n");
-  return `${imports}
-
-async function main() {
-  const browser = await chromium.launch({ headless: false });
-  const page = await browser.newPage();
-  const human = await createHuman(page, ${createHumanOptions(timeline)});
-
-${body}
-
-  await browser.close();
-}
-
-main();
-`;
-}
-var NAV_TYPES = /* @__PURE__ */ new Set(["goto", "reload", "goBack", "goForward"]);
-function sharedGotoOrigin(events) {
-  let origin;
-  for (const e of events) {
-    if (e.type !== "goto") continue;
-    try {
-      const o = new URL(String(e.params.url ?? "")).origin;
-      if (origin === void 0) origin = o;
-      else if (origin !== o) return void 0;
-    } catch {
-      return void 0;
-    }
-  }
-  return origin;
-}
-function indentLines(block, pad) {
-  return block.split("\n").map((line) => line.length > 0 ? pad + line : line).join("\n");
-}
-function stepLabel(event, index, baseOrigin) {
-  switch (event.type) {
-    case "goto": {
-      const url = String(event.params.url ?? "");
-      const path = baseOrigin && url.startsWith(baseOrigin) ? url.slice(baseOrigin.length) || "/" : url;
-      return `go to ${path}`;
-    }
-    case "reload":
-      return "reload";
-    case "goBack":
-      return "go back";
-    case "goForward":
-      return "go forward";
-    default:
-      return `step ${index + 1}`;
-  }
-}
-function emitSteps(events, opts) {
-  const groups = [];
-  for (const e of events) {
-    const last = groups[groups.length - 1];
-    if (last === void 0 || NAV_TYPES.has(e.type)) groups.push([e]);
-    else last.push(e);
-  }
-  return groups.map((group, i) => {
-    const [first] = group;
-    const label = first ? stepLabel(first, i, opts.baseOrigin) : `step ${i + 1}`;
-    const inner = group.map((e) => indentLines(emitAction(e, opts), "  ")).join("\n");
-    return `  await test.step(${q(label)}, async () => {
-${inner}
-  });`;
-  }).join("\n\n");
-}
-function generatePlaywrightTest(timeline, options = {}) {
-  const events = options.keepSleeps ? timeline.events : timeline.events.filter((e) => e.type !== "sleep");
-  const baseOrigin = options.baseUrl ? sharedGotoOrigin(events) : void 0;
-  const emitOpts = { asserts: true, baseOrigin };
-  const body = options.steps ? emitSteps(events, emitOpts) : events.map((e) => emitAction(e, emitOpts)).join("\n");
-  const needsSleep = events.some((e) => e.type === "sleep");
-  const hasAsserts = body.includes("await expect(");
-  const testImport = hasAsserts ? "import { expect, test } from '@playwright/test';" : "import { test } from '@playwright/test';";
-  const humanImport = needsSleep ? "import { createHuman, sleep } from '@humanjs/playwright';" : "import { createHuman } from '@humanjs/playwright';";
-  const title = options.title ?? timeline.name ?? "recorded session";
-  const baseUrlNote = baseOrigin ? `  // Set use.baseURL = ${q(baseOrigin)} in playwright.config.ts for these relative paths.
-
-` : "";
-  const todo = [
-    hasAsserts ? "  // TODO: add assertions for the outcome of this flow, e.g.:" : "  // TODO: assert the outcome \u2014 import { expect } from '@playwright/test', e.g.:",
-    "  //   await expect(page).toHaveURL(/dashboard/);",
-    "  //   await expect(page.getByText('Welcome back')).toBeVisible();"
-  ].join("\n");
-  return `${testImport}
-${humanImport}
-
-test(${q(title)}, async ({ page }) => {
-  const human = await createHuman(page, ${createHumanOptions(timeline, true)});
-
-${baseUrlNote}${body}
-
-${todo}
-});
-`;
-}
-
-// src/recording/index.ts
-var pendingFrameCleanups = /* @__PURE__ */ new Set();
-var exitHandlerInstalled = false;
-function ensureExitHandler() {
-  if (exitHandlerInstalled) return;
-  exitHandlerInstalled = true;
-  process.on("exit", () => {
-    for (const dir of pendingFrameCleanups) {
-      try {
-        rmSync(dir, { recursive: true, force: true });
-      } catch {
-      }
-    }
-    pendingFrameCleanups.clear();
-  });
-}
-var FFMPEG_PATH = ffmpegStatic;
-var QUALITY_PRESETS = {
-  fast: {
-    captureFormat: "jpeg",
-    captureJpegQuality: 85,
-    captureFps: 24,
-    crf: 23,
-    preset: "fast"
-  },
-  standard: {
-    captureFormat: "jpeg",
-    captureJpegQuality: 90,
-    captureFps: 30,
-    crf: 20,
-    preset: "fast"
-  },
-  high: {
-    captureFormat: "jpeg",
-    captureJpegQuality: 95,
-    captureFps: 30,
-    crf: 18,
-    preset: "slow",
-    // 'animation' suits screen content (large solid regions, sharp edges)
-    // better than 'film' which is tuned for live-action grain.
-    tune: "animation"
-  },
-  lossless: {
-    // PNG capture for perceptually lossless source frames. Temp files are
-    // 10-20× larger than JPEG; output mp4 still benefits from the extra
-    // headroom (no JPEG artifacts to preserve).
-    captureFormat: "png",
-    captureJpegQuality: 100,
-    captureFps: 30,
-    crf: 12,
-    preset: "veryslow",
-    tune: "animation"
-  }
-};
-function getCaptureSettingsForQuality(quality) {
-  const preset = QUALITY_PRESETS[quality];
-  return {
-    format: preset.captureFormat,
-    quality: preset.captureJpegQuality,
-    fps: preset.captureFps
-  };
-}
-var Recording = class {
-  #capture;
-  #windowStartMs;
-  #windowEndMs;
-  #timelineSource;
-  // Frames live on disk until `dispose()` is called. Exporters
-  // (`toVideo`, `toGif`) are repeatable and interleavable — they read the
-  // same frame source, they don't consume it.
-  #disposed = false;
-  constructor(capture, windowStartMs, windowEndMs, timelineSource) {
-    this.#capture = capture;
-    this.#windowStartMs = windowStartMs;
-    this.#windowEndMs = windowEndMs;
-    this.#timelineSource = timelineSource;
-    if (capture !== null) {
-      pendingFrameCleanups.add(capture.dir);
-      ensureExitHandler();
-    }
-  }
-  /** Wall-clock duration of the recorded window. */
-  get durationMs() {
-    return this.#windowEndMs - this.#windowStartMs;
-  }
-  /** True if frames were captured during this recording. */
-  get hasVideo() {
-    return this.#capture !== null;
-  }
-  /**
-   * The structured action timeline of this recording — same data that
-   * `toTimeline()` writes to disk.
-   */
-  get timeline() {
-    return {
-      version: 1,
-      ...this.#timelineSource.name !== void 0 ? { name: this.#timelineSource.name } : {},
-      personality: this.#timelineSource.personality,
-      seed: this.#timelineSource.seed,
-      speed: this.#timelineSource.speed,
-      durationMs: this.durationMs,
-      events: this.#timelineSource.events
-    };
-  }
-  /**
-   * Assembles the captured frames into a video at `outputPath`. The output
-   * format is inferred from the extension — `.mp4` (H.264, re-encoded
-   * with the configured quality) or `.webm` (VP9).
-   *
-   * Repeatable and interleavable with `toGif()` — the frame source is read,
-   * not consumed. Frames live until you call `dispose()` (or `await using`
-   * goes out of scope, or the process exits and the OS reaps `tmpdir`).
-   *
-   * @returns the resolved output path.
-   */
-  async toVideo(outputPath, options = {}) {
-    if (this.#disposed) {
-      throw new Error("Recording.toVideo() called after dispose() \u2014 the source frames are gone.");
-    }
-    if (this.#capture === null) {
-      throw new Error(
-        "Recording.toVideo() requires video capture, which was disabled for this recording. Call `human.record(cb)` (default captures video) or pass `output` to @humanjs/recorder's `record()`. `toTimeline()` and `.timeline` work without capture."
-      );
-    }
-    const preset = QUALITY_PRESETS[options.quality ?? "high"];
-    const crf = options.crf ?? preset.crf;
-    const ffmpegPreset = options.preset ?? preset.preset;
-    const tune = options.tune ?? preset.tune;
-    const { dir, frames, startedAtMs, stoppedAtMs } = this.#capture;
-    if (frames.length === 0) {
-      throw new Error(
-        "No frames were captured. The recording window may have been too short, or the page may not have rendered any frames before the callback completed."
-      );
-    }
-    await mkdir(dirname(outputPath), { recursive: true });
-    const ext = extname(outputPath).toLowerCase();
-    if (ext !== ".mp4" && ext !== ".webm") {
-      throw new Error(`Unsupported output extension: ${ext || "(none)"}. Use .mp4 or .webm.`);
-    }
-    const concatPath = `${dir}/concat.txt`;
-    const concatBody = buildConcatFile(frames, stoppedAtMs - startedAtMs);
-    await writeFile(concatPath, concatBody, "utf8");
-    const args = ["-y", "-f", "concat", "-safe", "0", "-i", concatPath, "-vsync", "vfr"];
-    if (ext === ".mp4") {
-      args.push(
-        "-c:v",
-        "libx264",
-        "-pix_fmt",
-        "yuv420p",
-        "-crf",
-        String(crf),
-        "-preset",
-        ffmpegPreset
-      );
-      if (tune) args.push("-tune", tune);
-      args.push("-movflags", "+faststart");
-    } else {
-      args.push(
-        "-c:v",
-        "libvpx-vp9",
-        "-pix_fmt",
-        "yuv420p",
-        "-crf",
-        String(crf),
-        "-b:v",
-        "0",
-        "-deadline",
-        ffmpegPreset === "fast" || ffmpegPreset === "veryfast" ? "realtime" : "good"
-      );
-    }
-    args.push(outputPath);
-    await runFfmpeg(args);
-    return outputPath;
-  }
-  /**
-   * Assembles the captured frames into an animated GIF at `outputPath`.
-   * Optimized for embedding in READMEs, PRs, Slack, and docs — uses a
-   * per-recording palette (`palettegen` + `paletteuse`) with Bayer dithering
-   * so gradients stay smooth without exploding the file size.
-   *
-   * Repeatable and interleavable with `toVideo()` — call them in any order,
-   * any number of times. Frames live until you call `dispose()`.
-   *
-   * @returns the resolved output path.
-   */
-  async toGif(outputPath, options = {}) {
-    if (this.#disposed) {
-      throw new Error("Recording.toGif() called after dispose() \u2014 the source frames are gone.");
-    }
-    if (this.#capture === null) {
-      throw new Error(
-        "Recording.toGif() requires video capture, which was disabled for this recording. Call `human.record(cb)` (default captures video) or pass `output` to @humanjs/recorder's `record()`. `toTimeline()` and `.timeline` work without capture."
-      );
-    }
-    const fps = options.fps ?? 15;
-    const width = options.width;
-    const { dir, frames, startedAtMs, stoppedAtMs } = this.#capture;
-    if (frames.length === 0) {
-      throw new Error(
-        "No frames were captured. The recording window may have been too short, or the page may not have rendered any frames before the callback completed."
-      );
-    }
-    await mkdir(dirname(outputPath), { recursive: true });
-    const ext = extname(outputPath).toLowerCase();
-    if (ext !== ".gif") {
-      throw new Error(`Unsupported output extension: ${ext || "(none)"}. Use .gif.`);
-    }
-    const concatPath = `${dir}/concat.txt`;
-    const concatBody = buildConcatFile(frames, stoppedAtMs - startedAtMs);
-    await writeFile(concatPath, concatBody, "utf8");
-    const filterSteps = [`fps=${fps}`];
-    if (width !== void 0) {
-      filterSteps.push(`scale=${width}:-1:flags=lanczos`);
-    }
-    const preFilter = filterSteps.join(",");
-    const filterComplex = `${preFilter},split [a][b]; [a] palettegen=stats_mode=diff [p]; [b][p] paletteuse=dither=bayer:bayer_scale=5`;
-    const args = [
-      "-y",
-      "-f",
-      "concat",
-      "-safe",
-      "0",
-      "-i",
-      concatPath,
-      "-filter_complex",
-      filterComplex,
-      "-loop",
-      "0",
-      outputPath
-    ];
-    await runFfmpeg(args);
-    return outputPath;
-  }
-  /**
-   * Writes the structured action timeline to `outputPath` as JSON.
-   * Independent of `toVideo()` / `toGif()` — call before, after, in between,
-   * or instead. Safe to call multiple times. Unaffected by `dispose()`
-   * (the timeline lives in memory, not in the captured-frames temp dir).
-   *
-   * @returns the resolved output path.
-   */
-  async toTimeline(outputPath) {
-    await mkdir(dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, `${JSON.stringify(this.timeline, null, 2)}
-`, "utf8");
-    return outputPath;
-  }
-  /**
-   * Generates a standalone, runnable HumanJS script from the timeline and
-   * writes it to `outputPath`. String selectors round-trip verbatim; typed
-   * values are included when `captureInputs` was on (passwords masked).
-   *
-   * Independent of frame capture — works on timeline-only recordings and is
-   * unaffected by `dispose()`.
-   *
-   * @returns the resolved output path.
-   */
-  async toHumanJS(outputPath) {
-    await mkdir(dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, generateHumanJS(this.timeline), "utf8");
-    return outputPath;
-  }
-  /**
-   * Generates a `@playwright/test` spec from the timeline — a humanized test
-   * (uses `createHuman` + `human.*`), not raw Playwright — and writes it to
-   * `outputPath`. Runs instant in CI / recorded speed locally, drops timing
-   * `sleep()`s (pass `{ keepSleeps: true }` to keep them), and derives the
-   * assertions it safely can.
-   *
-   * Independent of frame capture — works on timeline-only recordings and is
-   * unaffected by `dispose()`.
-   *
-   * @returns the resolved output path.
-   */
-  async toPlaywright(outputPath, options) {
-    await mkdir(dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, generatePlaywrightTest(this.timeline, options), "utf8");
-    return outputPath;
-  }
-  /**
-   * Releases the captured-frames temp directory. After this call, `toVideo()`
-   * and `toGif()` throw — but `toTimeline()` and the in-memory `timeline`
-   * still work because those don't depend on the frames.
-   *
-   * **Optional.** A process-exit handler also sweeps any un-disposed frame
-   * dirs, so casual scripts can skip this entirely. Call it explicitly when
-   * you want to release frames proactively (long-running services, batch
-   * jobs, or anywhere you want predictable disk usage).
-   *
-   * Idempotent. Safe to call on a Recording that never had a capture
-   * (timeline-only mode) — no-op there.
-   *
-   * Also wired to `Symbol.asyncDispose`, so the explicit-resource-management
-   * `await using` syntax (TypeScript ≥ 5.2 / Node ≥ 20.4) works:
-   *
-   * ```ts
-   * await using rec = await human.record(fn);
-   * await rec.toVideo('demo.mp4');
-   * await rec.toGif('demo.gif');
-   * // frames cleaned up automatically when `rec` goes out of scope
-   * ```
-   */
-  async dispose() {
-    if (this.#disposed) return;
-    if (this.#capture !== null) {
-      await this.#capture.cleanup();
-      pendingFrameCleanups.delete(this.#capture.dir);
-    }
-    this.#disposed = true;
-  }
-  async [Symbol.asyncDispose]() {
-    await this.dispose();
-  }
-};
-function buildConcatFile(frames, totalMs) {
-  const lines = [];
-  for (let i = 0; i < frames.length; i++) {
-    const frame = frames[i];
-    const next = frames[i + 1];
-    const nextTMs = next ? next.tMs : totalMs;
-    const durationS = Math.max(1e-3, (nextTMs - frame.tMs) / 1e3);
-    lines.push(`file '${frame.path.replaceAll("'", "'\\''")}'`);
-    lines.push(`duration ${durationS.toFixed(6)}`);
-  }
-  const last = frames[frames.length - 1];
-  if (last) {
-    lines.push(`file '${last.path.replaceAll("'", "'\\''")}'`);
-  }
-  return `${lines.join("\n")}
-`;
-}
-function runFfmpeg(args) {
-  if (!FFMPEG_PATH) {
-    return Promise.reject(
-      new Error(
-        "ffmpeg-static did not bundle a binary for this platform. Install system ffmpeg and set FFMPEG_PATH, or run on a supported platform."
-      )
-    );
-  }
-  return new Promise((resolve, reject) => {
-    const proc = spawn(FFMPEG_PATH, [...args]);
-    let stderr = "";
-    proc.stderr?.on("data", (chunk) => {
-      stderr += chunk.toString();
-    });
-    proc.on("error", reject);
-    proc.on("close", (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`ffmpeg exited with code ${code}
-${stderr.trim()}`));
-    });
-  });
-}
-async function startCapture(page, options = {}) {
-  const format = options.format ?? "jpeg";
-  const quality = options.quality ?? 95;
-  const fps = Math.max(1, Math.min(60, options.fps ?? 30));
-  const intervalMs = 1e3 / fps;
-  const dir = await mkdtemp(join(tmpdir(), "humanjs-capture-"));
-  const frames = [];
-  const ext = format === "png" ? "png" : "jpg";
-  let stopped = false;
-  let frameIndex = 0;
-  const writes = [];
-  const startedAtMs = Date.now();
-  const captureLoop = async () => {
-    while (!stopped) {
-      const loopStart = Date.now();
-      try {
-        const buf = await page.screenshot({
-          type: format,
-          quality: format === "jpeg" ? quality : void 0
-        });
-        if (stopped) return;
-        const idx = frameIndex++;
-        const path = join(dir, `frame_${String(idx).padStart(6, "0")}.${ext}`);
-        const tMs = loopStart - startedAtMs;
-        writes.push(
-          writeFile(path, buf).then(
-            () => {
-              frames.push({ path, tMs });
-            },
-            (err) => {
-              console.warn(`humanjs capture: write failed for frame ${idx}:`, err);
-            }
-          )
-        );
-      } catch (err) {
-        if (stopped) return;
-        console.warn("humanjs capture: screenshot failed, stopping loop:", err);
-        stopped = true;
-        return;
-      }
-      const elapsed = Date.now() - loopStart;
-      const wait = intervalMs - elapsed;
-      if (wait > 0) await sleep$1(wait);
-    }
-  };
-  const loopPromise = captureLoop();
-  const finish = async () => {
-    stopped = true;
-    await loopPromise;
-    await Promise.allSettled(writes);
-  };
-  return {
-    async stop() {
-      await finish();
-      const stoppedAtMs = Date.now();
-      return {
-        dir,
-        frames: [...frames].sort((a, b) => a.tMs - b.tMs),
-        startedAtMs,
-        stoppedAtMs,
-        format,
-        fps,
-        cleanup: () => rm(dir, { recursive: true, force: true }).then(() => void 0)
-      };
-    },
-    async abort() {
-      await finish();
-      await rm(dir, { recursive: true, force: true }).catch(() => void 0);
-    }
-  };
-}
-
-// src/mouse-helper/index.ts
-var CURSOR_PATH = "M 0 0 L 16 6 L 8 9.5 L 5 19 Z";
-var INSTALLED_FLAG = /* @__PURE__ */ Symbol.for("@humanjs/playwright:mouse-helper:installed");
-async function installMouseHelper(target, options = {}) {
-  const tagged = target;
-  if (tagged[INSTALLED_FLAG]) return;
-  tagged[INSTALLED_FLAG] = true;
-  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 attachPageHooks = (page) => {
-    page.on("domcontentloaded", () => {
-      page.evaluate(installScript, config).catch(() => void 0);
-    });
-  };
-  const pages = "pages" in target ? target.pages() : [target];
-  for (const page of pages) attachPageHooks(page);
-  if ("on" in target && "newPage" in target) {
-    target.on("page", attachPageHooks);
-  }
-  await Promise.all(
-    pages.map((page) => page.evaluate(installScript, config).catch(() => void 0))
-  );
-}
-function installScript(config) {
-  if (document.querySelector("[data-humanjs-cursor]")) return;
-  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 = {}) {
-  const personality = resolvePersonality(options.personality ?? "careful");
-  const rng = createRng(options.seed);
-  const speed = options.speed ?? "human";
-  const plugins = options.plugins ?? [];
-  const context = { personality, rng };
-  for (const plugin of plugins) {
-    await plugin.install?.(context);
-  }
-  let hasRecorded = false;
-  let activeRecordingEvents = null;
-  let activeRecordingStartMs = 0;
-  let activeRecordingCaptureInputs = false;
-  async function performAction(action, actionFn, recordMeta) {
-    for (const plugin of plugins) {
-      await plugin.beforeAction?.(action);
-    }
-    const startedAt = Date.now();
-    try {
-      const value = await actionFn();
-      const durationMs = Date.now() - startedAt;
-      const result = { type: action.type, durationMs };
-      if (activeRecordingEvents !== null && action.type !== "record") {
-        activeRecordingEvents.push({
-          type: action.type,
-          params: action.params ?? {},
-          tMs: startedAt - activeRecordingStartMs,
-          durationMs,
-          ...recordMeta?.inputValue !== void 0 ? { inputValue: recordMeta.inputValue } : {}
-        });
-      }
-      for (const plugin of plugins) {
-        await plugin.afterAction?.(action, result);
-      }
-      return value;
-    } catch (error) {
-      if (activeRecordingEvents !== null && action.type !== "record") {
-        activeRecordingEvents.push({
-          type: action.type,
-          params: action.params ?? {},
-          tMs: startedAt - activeRecordingStartMs,
-          durationMs: Date.now() - startedAt,
-          error: error instanceof Error ? error.message : String(error),
-          ...recordMeta?.inputValue !== void 0 ? { inputValue: recordMeta.inputValue } : {}
-        });
-      }
-      for (const plugin of plugins) {
-        await plugin.onError?.(action, error);
-      }
-      throw error;
-    }
-  }
-  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";
-  };
-  const isPointTarget = (target) => typeof target !== "string" && "x" in target && "y" in target && typeof target.x === "number";
-  const captureInputValue = async (target, value) => {
-    if (activeRecordingEvents === null || !activeRecordingCaptureInputs) return void 0;
-    const locator = typeof target === "string" ? page.locator(target) : isPointTarget(target) ? null : target;
-    if (locator !== null) {
-      try {
-        const fieldType = await locator.first().getAttribute("type", { timeout: 1e3 });
-        if (fieldType?.toLowerCase() === "password") {
-          return void 0;
-        }
-      } catch {
-      }
-    }
-    return value;
-  };
-  return {
-    personality,
-    speed,
-    async goto(url) {
-      await performAction({ type: "goto", params: { url } }, async () => {
-        await page.goto(url);
-      });
-    },
-    async click(target) {
-      const description = describeMouseTarget(target);
-      await performAction({ type: "click", params: { target: description } }, async () => {
-        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 = describeMouseTarget(target);
-      const inputValue = await captureInputValue(target, value);
-      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 });
-        },
-        inputValue !== void 0 ? { inputValue } : void 0
-      );
-    },
-    async paste(target, value) {
-      const description = describeMouseTarget(target);
-      const inputValue = await captureInputValue(target, value);
-      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 });
-        },
-        inputValue !== void 0 ? { inputValue } : void 0
-      );
-    },
-    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(
-        {
-          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)
-      );
-    },
-    async sleep(ms) {
-      await performAction({ type: "sleep", params: { ms } }, () => sleep$1(ms));
-    },
-    async record(optionsOrFn, maybeFn) {
-      const [recordOptions, fn] = typeof optionsOrFn === "function" ? [{}, optionsOrFn] : [optionsOrFn, maybeFn];
-      if (hasRecorded) {
-        throw new Error(
-          "human.record() can only be called once per session. Create a new browser context (and a new human session) to record a separate clip."
-        );
-      }
-      hasRecorded = true;
-      const captureEnabled = recordOptions.video !== false;
-      const captureQuality = recordOptions.quality ?? "high";
-      let captureSession = null;
-      if (captureEnabled) {
-        const { format, quality, fps } = getCaptureSettingsForQuality(captureQuality);
-        captureSession = await startCapture(page, { format, quality, fps });
-      }
-      const events = [];
-      const windowStartMs = Date.now();
-      activeRecordingEvents = events;
-      activeRecordingStartMs = windowStartMs;
-      activeRecordingCaptureInputs = recordOptions.captureInputs !== false;
-      let windowEndMs = windowStartMs;
-      try {
-        await performAction({ type: "record", params: {} }, async () => {
-          try {
-            await fn();
-          } finally {
-            windowEndMs = Date.now();
-          }
-        });
-      } catch (error) {
-        if (captureSession) await captureSession.abort();
-        throw error;
-      } finally {
-        activeRecordingEvents = null;
-        activeRecordingCaptureInputs = false;
-      }
-      const captureResult = captureSession ? await captureSession.stop() : null;
-      return new Recording(captureResult, windowStartMs, windowEndMs, {
-        name: recordOptions.name,
-        personality: personality.name,
-        seed: options.seed === void 0 ? null : String(options.seed),
-        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);
-    }
-  };
-}
-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 { Recording, createHuman, installMouseHelper };
+export { Recording, applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, chromium, computeReadingDwellMs, countWords, createHuman, createRng, distracted, fast, firefox, humanizePath, installMouseHelper, planScroll, planTypeKeystrokes, precise, resolvePersonality, sleep, webkit } from './chunk-CCZEDNOF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map