@humanjs/playwright 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,5 +1,12 @@
-import { resolvePersonality, createRng, planScroll, countWords, computeReadingDwellMs, planReadingScan, planTypeKeystrokes, bezierPath, humanizePath } from '@humanjs/core';
-export { applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, computeReadingDwellMs, countWords, createRng, distracted, fast, humanizePath, planScroll, planTypeKeystrokes, precise, resolvePersonality } from '@humanjs/core';
+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
 
@@ -56,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) {
@@ -70,168 +144,6 @@ async function walkMouseAlongPath(page, path, durationMs) {
     }
   }
 }
-
-// src/mouse/index.ts
-async function executeClick(target, ctx) {
-  const locator = typeof target === "string" ? ctx.page.locator(target) : target;
-  if (ctx.speed === "instant") {
-    const box2 = await locator.boundingBox();
-    await locator.click();
-    const center = box2 ? { x: box2.x + box2.width / 2, y: box2.y + box2.height / 2 } : ctx.getMousePosition();
-    ctx.setMousePosition(center);
-    return { target: center };
-  }
-  const box = await locator.boundingBox();
-  if (!box) {
-    throw new Error(
-      `Cannot click: element not found or has no bounding box (target: ${describeTarget(target)})`
-    );
-  }
-  const targetPoint = pickClickPoint(box, ctx.rng);
-  const startPoint = ctx.getMousePosition();
-  const rawPath = bezierPath(startPoint, targetPoint, ctx.rng, {
-    curvature: ctx.personality.mouse.curvature
-  });
-  const path = humanizePath(rawPath, ctx.rng);
-  const travelMs = computeTravelTime(path, ctx.personality, ctx.speed, ctx.rng);
-  await walkMouseAlongPath(ctx.page, path, travelMs);
-  const preClickMs = computeDwellTime(
-    ctx.personality.dwell.preClickMs,
-    ctx.personality.dwell.preClickJitter,
-    ctx.personality,
-    ctx.speed,
-    ctx.rng
-  );
-  if (preClickMs > 0) await sleep(preClickMs);
-  ctx.setMousePosition(targetPoint);
-  await ctx.page.mouse.click(targetPoint.x, targetPoint.y);
-  const postActionMs = computeDwellTime(
-    ctx.personality.dwell.postActionMs,
-    ctx.personality.dwell.postActionJitter,
-    ctx.personality,
-    ctx.speed,
-    ctx.rng
-  );
-  if (postActionMs > 0) await sleep(postActionMs);
-  return { target: targetPoint };
-}
-function pickClickPoint(box, rng) {
-  const cx = box.x + box.width / 2;
-  const cy = box.y + box.height / 2;
-  const x = clamp(cx + rng.nextGaussian(0, box.width / 8), box.x, box.x + box.width);
-  const y = clamp(cy + rng.nextGaussian(0, box.height / 8), box.y, box.y + box.height);
-  return { x, y };
-}
-function computeTravelTime(path, personality, speed, rng) {
-  let distance = 0;
-  for (let i = 1; i < path.length; i++) {
-    const prev = path[i - 1];
-    const curr = path[i];
-    if (!prev || !curr) continue;
-    distance += Math.hypot(curr.x - prev.x, curr.y - prev.y);
-  }
-  const baseTime = distance / 1e3 * personality.mouse.travelTimeMs;
-  const jitterMag = baseTime * personality.mouse.travelTimeJitter;
-  const jitter = rng.nextFloat(-jitterMag, jitterMag);
-  const total = (baseTime + jitter) * personality.speed * speedModeFactor(speed);
-  return Math.max(0, total);
-}
-function describeTarget(target) {
-  return typeof target === "string" ? target : target.toString?.() ?? "locator";
-}
-function clamp(value, min, max) {
-  return value < min ? min : value > max ? max : value;
-}
-async function executeRead(target, ctx, options = {}) {
-  let words = 0;
-  let locator;
-  if (typeof target === "string") {
-    locator = ctx.page.locator(target);
-  } else if ("words" in target) {
-    words = target.words;
-  } else if ("text" in target) {
-    words = countWords(target.text);
-  } else {
-    locator = target;
-  }
-  let autoDetectedKind;
-  if (locator) {
-    if (options.scrollIntoView) {
-      await locator.scrollIntoViewIfNeeded();
-    }
-    const text = await locator.innerText().catch(() => "");
-    words = countWords(text);
-    if (options.kind === void 0) {
-      autoDetectedKind = await detectKindFromTag(locator);
-    }
-  }
-  const kind = options.kind ?? autoDetectedKind ?? "prose";
-  const durationMs = computeReadingDwellMs(words, ctx.personality.reading, ctx.rng, {
-    kind,
-    wpmMultiplier: options.wpmMultiplier,
-    personalitySpeed: ctx.personality.speed,
-    speedFactor: speedModeFactor(ctx.speed)
-  });
-  if (options.withMotion && locator && durationMs > 0) {
-    const box = await locator.boundingBox().catch(() => null);
-    if (box) {
-      const lineRects = await getLineRects(locator).catch(() => []);
-      const path = planReadingScan(box, ctx.rng, {
-        start: ctx.getMousePosition(),
-        lineRects: lineRects.length > 0 ? lineRects : void 0
-      });
-      await walkMouseAlongPath(ctx.page, path, durationMs);
-      const final = path[path.length - 1];
-      if (final) ctx.setMousePosition(final);
-      return { words, durationMs, kind };
-    }
-  }
-  if (durationMs > 0) await sleep(durationMs);
-  return { words, durationMs, kind };
-}
-async function getLineRects(locator) {
-  const result = await locator.evaluate((el) => {
-    const walker = el.ownerDocument.createTreeWalker(el, 4);
-    const rects = [];
-    let node = walker.nextNode();
-    while (node) {
-      const text = node.textContent ?? "";
-      if (text.trim().length > 0) {
-        const range = el.ownerDocument.createRange();
-        range.selectNodeContents(node);
-        for (const r of Array.from(range.getClientRects())) {
-          if (r.width > 0 && r.height > 0) {
-            rects.push({ x: r.x, y: r.y, width: r.width, height: r.height });
-          }
-        }
-      }
-      node = walker.nextNode();
-    }
-    rects.sort((a, b) => a.y - b.y || a.x - b.x);
-    const merged = [];
-    for (const r of rects) {
-      const last = merged[merged.length - 1];
-      if (last && Math.abs(last.y - r.y) < 1 && r.x - (last.x + last.width) < 6) {
-        const right = Math.max(last.x + last.width, r.x + r.width);
-        const bottom = Math.max(last.y + last.height, r.y + r.height);
-        last.width = right - last.x;
-        last.height = bottom - last.y;
-      } else {
-        merged.push({ ...r });
-      }
-    }
-    return merged;
-  });
-  if (!Array.isArray(result)) return [];
-  return result.filter(
-    (r) => r != null && typeof r === "object" && typeof r.x === "number" && typeof r.y === "number" && typeof r.width === "number" && typeof r.height === "number"
-  );
-}
-async function detectKindFromTag(locator) {
-  const tag = await locator.evaluate((el) => el.tagName?.toLowerCase() ?? "").catch(() => "");
-  if (tag === "pre" || tag === "code") return "code";
-  return void 0;
-}
 var RESERVED_TARGETS = /* @__PURE__ */ new Set(["natural", "end", "top"]);
 async function executeScroll(target, ctx, options = {}) {
   const { page, personality, rng, speed } = ctx;
@@ -244,7 +156,7 @@ async function executeScroll(target, ctx, options = {}) {
   }
   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 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 };
@@ -401,13 +313,797 @@ async function walkSegments(page, segments, axis, container) {
     }
   }
 }
+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";
+  const locator = typeof target === "string" ? ctx.page.locator(target) : target;
+  if (ctx.speed === "instant") {
+    const box = await locator.boundingBox();
+    await locator.click({ button });
+    const center = box ? { x: box.x + box.width / 2, y: box.y + box.height / 2 } : ctx.getMousePosition();
+    ctx.setMousePosition(center);
+    return { target: center };
+  }
+  const targetPoint = await moveToTarget(target, ctx, "click");
+  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, "hover");
+  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, action) {
+  const box = await readBoxWithAutoScroll(target, ctx, action);
+  const targetPoint = pickClickPoint(box, ctx.rng, ctx.personality.mouse.clickSpread);
+  if (action === "click") await maybeMisclickBeat(ctx, box, targetPoint);
+  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;
+}
+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,
+      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;
+  }
+  /**
+   * 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",
@@ -417,16 +1113,22 @@ async function installMouseHelper(target, options = {}) {
     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) {
-  const guardKey = "__humanjsMouseHelperInstalled";
-  const w = window;
-  if (w[guardKey]) return;
-  w[guardKey] = true;
+  if (document.querySelector("[data-humanjs-cursor]")) return;
   const attach = () => {
     const cursor = document.createElement("div");
     cursor.setAttribute("aria-hidden", "true");
@@ -517,6 +1219,9 @@ async function createHuman(page, options = {}) {
   for (const plugin of plugins) {
     await plugin.install?.(context);
   }
+  let hasRecorded = false;
+  let activeRecordingEvents = null;
+  let activeRecordingStartMs = 0;
   async function performAction(action, actionFn) {
     for (const plugin of plugins) {
       await plugin.beforeAction?.(action);
@@ -524,15 +1229,30 @@ async function createHuman(page, options = {}) {
     const startedAt = Date.now();
     try {
       const value = await actionFn();
-      const result = {
-        type: action.type,
-        durationMs: Date.now() - startedAt
-      };
+      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
+        });
+      }
       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)
+        });
+      }
       for (const plugin of plugins) {
         await plugin.onError?.(action, error);
       }
@@ -540,6 +1260,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,
@@ -549,29 +1286,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(
@@ -610,6 +1383,51 @@ async function createHuman(page, options = {}) {
         },
         () => 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;
+      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;
+      }
+      const captureResult = captureSession ? await captureSession.stop() : null;
+      return new Recording(captureResult, windowStartMs, windowEndMs, {
+        personality: personality.name,
+        seed: options.seed === void 0 ? null : String(options.seed),
+        speed,
+        events
+      });
     }
   };
 }
@@ -629,6 +1447,6 @@ function describeReadTarget(target) {
   return target.toString?.() ?? "locator";
 }
 
-export { createHuman, installMouseHelper };
+export { Recording, createHuman, installMouseHelper };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map