@humanjs/playwright 0.3.0 → 0.4.0

package/README.md

@@ -75,15 +75,16 @@ await human.read('ul.changelog', { kind: 'scan' });    // explicit skim
 
 Explicit `kind` always wins over auto-detection.
 
-**Visible eye-scan motion** during the dwell:
+**Eye-scan cursor motion** runs during the dwell by default:
 
 ```ts
-await human.read('article', { withMotion: true });
+await human.read('article');                       // motion: on
+await human.read('article', { withMotion: false }); // motion: off
 ```
 
-The cursor walks a humanized L→R sweep through every line of rendered text and emits a small return-saccade between lines — same `mousemove` events a real reader would dispatch (so reading-time tooltip / hover handlers fire). Off by default.
+The cursor walks a humanized L→R sweep through every line of rendered text and emits a small return-saccade between lines — same `mousemove` events a real reader would dispatch (so reading-time tooltip / hover handlers fire). Pass `{ withMotion: false }` when you only care about the temporal pattern (typical AI-agent use case).
 
-For demos and screen recordings, pair `withMotion` with `installMouseHelper(page)` to render a visible cursor that follows the synthetic motion:
+For demos and screen recordings, pair it with `installMouseHelper(page)` to render a visible cursor that follows the synthetic motion:
 
 ```ts
 import { createHuman, installMouseHelper } from '@humanjs/playwright';
@@ -93,7 +94,7 @@ await page.goto('https://example.com/article');
 await installMouseHelper(page);
 
 const human = await createHuman(page, { personality: 'careful' });
-await human.read('article', { withMotion: true });
+await human.read('article');
 ```
 
 **Returns** a `ReadResult`:
@@ -171,6 +172,91 @@ In `speed: 'instant'`, the page jumps directly via `window.scrollTo` — no whee
 
 See [humanjs.dev](https://humanjs.dev) for the full feature set and personality reference.
 
+### Recording
+
+```ts
+import { chromium, createHuman, installMouseHelper } from '@humanjs/playwright';
+
+const browser = await chromium.launch({ headless: false });
+const context = await browser.newContext({ viewport: { width: 1920, height: 1080 } });
+const page = await context.newPage();
+
+// Visible cursor overlay so the recorded video shows mouse motion.
+await installMouseHelper(context);
+
+const human = await createHuman(page);
+
+const rec = await human.record(async () => {
+  await human.click('#login');
+  await human.type('#email', 'demo@humanjs.dev');
+});
+
+await rec.toVideo('demo.mp4');
+await rec.toTimeline('demo.json');
+await browser.close();
+```
+
+`human.record(cb)` polls `page.screenshot()` at the target FPS, writes each frame to a temp directory, then assembles them via ffmpeg when you call an exporter:
+
+- `rec.toVideo(path)` — `.mp4` (H.264 / yuv420p) or `.webm` (VP9)
+- `rec.toGif(path, { fps?, width? })` — palette-optimized animated GIF (`palettegen` + `paletteuse`, Bayer dither). Defaults to 15 fps, source viewport size.
+
+Both exporters are **repeatable and interleavable** — they read the captured frames, they don't consume them. Want an mp4 for the landing page *and* a GIF for the README from the same recording? Just call both:
+
+```ts
+const rec = await human.record(fn);
+await rec.toVideo('demo.mp4');
+await rec.toGif('demo.gif', { width: 720 });
+// No explicit cleanup needed for one-shot scripts — see below.
+```
+
+Captured frames live in a temp directory under `os.tmpdir()`. Cleanup happens automatically at process exit (a single `process.on('exit')` handler sweeps any un-disposed frame dirs), so casual scripts don't have to think about it. For long-running services, batch jobs, or anywhere you want predictable disk usage, release them proactively:
+
+```ts
+await rec.dispose();                  // explicit, idempotent
+// or with TS ≥ 5.2 / Node ≥ 20.4:
+await using rec = await human.record(fn);   // auto-disposes at scope exit
+```
+
+The same `Recording` exposes a **structured action timeline** of everything that happened during the callback:
+
+```ts
+await rec.toTimeline('session.json');   // → JSON on disk
+const timeline = rec.timeline;          // → in-memory object
+```
+
+The shape (`Timeline` with `personality`, `seed`, `speed`, `durationMs`, and an `events` array of `{ type, params, tMs, durationMs }`) is intended for observability pipelines, replay infrastructure, analytics, and debugger UIs. `toTimeline()` doesn't touch the browser context — call it before or after `toVideo()`, multiple times, in any order.
+
+**Quality presets** trade off file size, encoding time, and visual fidelity. Defaults to `'high'`:
+
+```ts
+await rec.toVideo('demo.mp4', { quality: 'high' });
+// 'fast'     — JPEG q=85, CRF 23, preset fast            (iteration)
+// 'standard' — JPEG q=90, CRF 20, preset fast            (balanced)
+// 'high'     — JPEG q=95, CRF 18, preset slow, animation (DEFAULT)
+// 'lossless' — PNG capture, CRF 12, preset veryslow      (archival)
+```
+
+Individual ffmpeg knobs (`crf`, `preset`, `tune`) can override the preset for fine-grained control.
+
+**Timeline-only mode** — skip the capture overhead entirely when you only need the action timeline:
+
+```ts
+const rec = await human.record({ video: false }, async () => {
+  await human.click('#login');
+});
+await rec.toTimeline('session.json');   // works
+// rec.toVideo('demo.mp4')               // throws with a clear message
+```
+
+**Lifecycle notes**:
+
+- Each session can produce **one** recording. `human.record()` throws if called twice on the same session — open a new context (and a new human) to record a separate clip.
+- `Recording.toVideo()` / `Recording.toGif()` are repeatable and interleavable. Frames live until `rec.dispose()` (or `await using` goes out of scope, or the process exits — a sweep-on-exit handler covers forgotten disposes).
+- For a one-call API that owns the entire lifecycle (launch → record → close), use [`@humanjs/recorder`](../recorder)'s `record(options, fn)` instead.
+
+Every recording is a regular plugin action — `beforeAction` and `afterAction` observe `{ type: 'record' }` exactly like `'click'` or `'scroll'`.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -1,6 +1,17 @@
 'use strict';
 
 var core = require('@humanjs/core');
+var child_process = require('child_process');
+var fs = require('fs');
+var promises = require('fs/promises');
+var path = require('path');
+var ffmpegStatic = require('ffmpeg-static');
+var os = require('os');
+var playwright = require('playwright');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var ffmpegStatic__default = /*#__PURE__*/_interopDefault(ffmpegStatic);
 
 // src/index.ts
 
@@ -173,7 +184,8 @@ async function executeRead(target, ctx, options = {}) {
     personalitySpeed: ctx.personality.speed,
     speedFactor: speedModeFactor(ctx.speed)
   });
-  if (options.withMotion && locator && durationMs > 0) {
+  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(() => []);
@@ -233,6 +245,396 @@ async function detectKindFromTag(locator) {
   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 {
+        fs.rmSync(dir, { recursive: true, force: true });
+      } catch {
+      }
+    }
+    pendingFrameCleanups.clear();
+  });
+}
+var FFMPEG_PATH = ffmpegStatic__default.default;
+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 promises.mkdir(path.dirname(outputPath), { recursive: true });
+    const ext = path.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 promises.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 promises.mkdir(path.dirname(outputPath), { recursive: true });
+    const ext = path.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 promises.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 promises.mkdir(path.dirname(outputPath), { recursive: true });
+    await promises.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 = child_process.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 promises.mkdtemp(path.join(os.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$1 = path.join(dir, `frame_${String(idx).padStart(6, "0")}.${ext}`);
+        const tMs = loopStart - startedAtMs;
+        writes.push(
+          promises.writeFile(path$1, buf).then(
+            () => {
+              frames.push({ path: path$1, 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 core.sleep(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: () => promises.rm(dir, { recursive: true, force: true }).then(() => void 0)
+      };
+    },
+    async abort() {
+      await finish();
+      await promises.rm(dir, { recursive: true, force: true }).catch(() => void 0);
+    }
+  };
+}
 var RESERVED_TARGETS = /* @__PURE__ */ new Set(["natural", "end", "top"]);
 async function executeScroll(target, ctx, options = {}) {
   const { page, personality, rng, speed } = ctx;
@@ -408,7 +810,11 @@ function clamp2(value, min, max) {
 
 // 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",
@@ -418,16 +824,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");
@@ -518,6 +930,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);
@@ -525,15 +940,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);
       }
@@ -611,6 +1041,51 @@ async function createHuman(page, options = {}) {
         },
         () => executeScroll(target, { page, personality, rng, speed }, options2)
       );
+    },
+    async sleep(ms) {
+      await performAction({ type: "sleep", params: { ms } }, () => core.sleep(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
+      });
     }
   };
 }
@@ -690,6 +1165,23 @@ Object.defineProperty(exports, "resolvePersonality", {
   enumerable: true,
   get: function () { return core.resolvePersonality; }
 });
+Object.defineProperty(exports, "sleep", {
+  enumerable: true,
+  get: function () { return core.sleep; }
+});
+Object.defineProperty(exports, "chromium", {
+  enumerable: true,
+  get: function () { return playwright.chromium; }
+});
+Object.defineProperty(exports, "firefox", {
+  enumerable: true,
+  get: function () { return playwright.firefox; }
+});
+Object.defineProperty(exports, "webkit", {
+  enumerable: true,
+  get: function () { return playwright.webkit; }
+});
+exports.Recording = Recording;
 exports.createHuman = createHuman;
 exports.installMouseHelper = installMouseHelper;
 //# sourceMappingURL=index.cjs.map