@humanjs/playwright 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { ReadKind, PersonalityConfig, HumanPlugin, Point, Personality } from '@humanjs/core';
-export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions, DwellProfile, HumanAction, HumanPlugin, HumanizePathOptions, Keystroke, KnownActionType, MouseProfile, Personality, PersonalityConfig, PersonalityExtension, PlanTypingOptions, PluginContext, Point, PresetName, ReadKind, ReadingProfile, Rng, ScrollProfile, ScrollSegment, TypingProfile, applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, computeReadingDwellMs, countWords, createRng, distracted, fast, humanizePath, planScroll, planTypeKeystrokes, precise, resolvePersonality } from '@humanjs/core';
+export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions, DwellProfile, HumanAction, HumanPlugin, HumanizePathOptions, Keystroke, KnownActionType, MouseProfile, Personality, PersonalityConfig, PersonalityExtension, PlanTypingOptions, PluginContext, Point, PresetName, ReadKind, ReadingProfile, Rng, ScrollProfile, ScrollSegment, TypingProfile, applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, computeReadingDwellMs, countWords, createRng, distracted, fast, humanizePath, planScroll, planTypeKeystrokes, precise, resolvePersonality, sleep } from '@humanjs/core';
 import { Locator, BrowserContext, Page } from 'playwright';
+export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } from 'playwright';
 
 /**
  * What to read:
@@ -39,9 +40,10 @@ interface ReadOptions {
     /**
      * For selector/Locator targets: trace a humanized cursor path through the
      * target's bounding box while the dwell elapses, like an eye tracking
-     * lines of text. Off by default — opt in when you want the humanization
-     * signal (or when reading-time mouseover behavior matters, e.g. tooltips
-     * that activate while a real user's cursor moves over the content).
+     * lines of text. **Defaults to `true`** — "reading" implies looking, and
+     * looking implies motion. Pass `false` to skip motion when you only
+     * care about the temporal pattern (typical AI-agent use case where
+     * the cursor position is irrelevant).
      *
      * The scan path is generated by `planReadingScan` from `@humanjs/core`
      * (same deterministic-by-seed contract as the rest of the library) and
@@ -63,6 +65,183 @@ interface ReadResult {
     readonly kind: ReadKind;
 }
 
+/**
+ * A captured frame in the timer-based capture session. `tMs` is the
+ * wall-clock offset (ms) from the capture start.
+ */
+interface CapturedFrame {
+    readonly path: string;
+    readonly tMs: number;
+}
+/** Outcome of a finalized capture session. */
+interface CaptureResult {
+    readonly dir: string;
+    readonly frames: readonly CapturedFrame[];
+    readonly startedAtMs: number;
+    readonly stoppedAtMs: number;
+    readonly format: 'jpeg' | 'png';
+    readonly fps: number;
+    /**
+     * Removes the temp directory + all frames. Called by `Recording.dispose()`
+     * and by the sweep-on-exit handler — not by the exporters, which are
+     * repeatable and read the frames without consuming them. Also called
+     * directly by the error path in `human.record()` when the callback throws.
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * Encoding quality preset. Picks the per-frame capture quality + the
+ * ffmpeg encode settings used to assemble them into a video.
+ *
+ * - `'fast'` — JPEG q=85, CRF 23, preset fast (iteration)
+ * - `'standard'` — JPEG q=90, CRF 20, preset fast (balanced)
+ * - `'high'` (default) — JPEG q=95, CRF 18, preset slow, tune animation (marketing-grade)
+ * - `'lossless'` — PNG capture, CRF 12, preset veryslow (archival; huge temp files)
+ */
+type RecordingQuality = 'fast' | 'high' | 'lossless' | 'standard';
+/** ffmpeg `-preset` values, ordered from fastest to slowest. */
+type FfmpegPreset = 'fast' | 'faster' | 'medium' | 'slow' | 'slower' | 'superfast' | 'ultrafast' | 'veryfast' | 'veryslow';
+/** ffmpeg `-tune` values for libx264. */
+type FfmpegTune = 'animation' | 'fastdecode' | 'film' | 'grain' | 'stillimage' | 'zerolatency';
+/** Options for {@link Recording.toVideo}. */
+interface ToVideoOptions {
+    /** Encoding quality preset. Defaults to `'high'`. */
+    readonly quality?: RecordingQuality;
+    /** Override CRF (0–51, lower = better). Defaults to the quality preset's CRF. */
+    readonly crf?: number;
+    /** Override ffmpeg `-preset`. Defaults to the quality preset's preset. */
+    readonly preset?: FfmpegPreset;
+    /** Override ffmpeg `-tune`. Defaults to the quality preset's tune (if any). */
+    readonly tune?: FfmpegTune;
+}
+/** Options for {@link Recording.toGif}. */
+interface ToGifOptions {
+    /**
+     * Frames per second of the output GIF. Defaults to `15` — high enough for
+     * smooth motion in most renderers, low enough to keep file size sane.
+     * Renderers cap GIF playback around 50fps anyway.
+     */
+    readonly fps?: number;
+    /**
+     * Scale the GIF to this width (pixels). Height is computed to preserve
+     * aspect ratio. Omit to keep the source viewport size — but most embedded
+     * GIFs (README, PR, Slack) look fine at 640–960px and weigh a fraction.
+     */
+    readonly width?: number;
+}
+/** One action captured during a recording, as emitted in {@link Timeline.events}. */
+interface TimelineEvent {
+    readonly type: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    /** Offset (ms) from the recording start when the action began. */
+    readonly tMs: number;
+    readonly durationMs: number;
+    /** Error message, present only if the action threw. */
+    readonly error?: string;
+}
+/** Structured action timeline of a recording. */
+interface Timeline {
+    readonly version: 1;
+    readonly personality: string;
+    readonly seed: string | null;
+    readonly speed: string;
+    readonly durationMs: number;
+    readonly events: readonly TimelineEvent[];
+}
+/** Metadata passed from `human.record()` into the Recording constructor. */
+interface RecordingTimelineSource {
+    readonly personality: string;
+    readonly seed: string | null;
+    readonly speed: string;
+    readonly events: readonly TimelineEvent[];
+}
+/**
+ * A recorded window of a humanized session. Returned by `human.record(cb)`.
+ *
+ * A Recording can hold a frame capture (`hasVideo === true`) OR be
+ * timeline-only (`hasVideo === false`). `toVideo()` / `toGif()` require a
+ * capture; `toTimeline()` and `.timeline` work either way.
+ *
+ * The video exporters are repeatable and interleavable — they read the
+ * captured frames without consuming them. Calling `dispose()` is OPTIONAL:
+ * the captured-frames temp dir is also swept by a `process.on('exit')`
+ * handler installed on first use, so casual scripts can skip it entirely.
+ * Call `dispose()` (or use `await using`) when you want to release the
+ * frames proactively — long-running services, batch jobs, etc.
+ */
+declare class Recording {
+    #private;
+    constructor(capture: CaptureResult | null, windowStartMs: number, windowEndMs: number, timelineSource: RecordingTimelineSource);
+    /** Wall-clock duration of the recorded window. */
+    get durationMs(): number;
+    /** True if frames were captured during this recording. */
+    get hasVideo(): boolean;
+    /**
+     * The structured action timeline of this recording — same data that
+     * `toTimeline()` writes to disk.
+     */
+    get timeline(): Timeline;
+    /**
+     * 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.
+     */
+    toVideo(outputPath: string, options?: ToVideoOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    toGif(outputPath: string, options?: ToGifOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    toTimeline(outputPath: string): Promise<string>;
+    /**
+     * 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
+     * ```
+     */
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
 /**
  * What / where to scroll. The chosen axis (`'y'` by default, `'x'` via
  * `options.axis`) decides whether targets resolve along the vertical or
@@ -165,31 +344,6 @@ interface InstallMouseHelperOptions {
     /** Halo opacity behind the cursor. Defaults to `0.18`. */
     readonly haloOpacity?: number;
 }
-/**
- * Installs a visual cursor overlay that follows every `mousemove` on each
- * page in the target. Real synthetic motion from Playwright (e.g.
- * `human.click()`, `human.read(..., { withMotion: true })`) is *already*
- * happening — the page just doesn't render a system cursor for it. This
- * helper injects a HumanJS-styled SVG cursor that listens to mousemove
- * events and follows them, making the motion visible in headed demos and
- * screen recordings.
- *
- * Re-runs on every navigation via `addInitScript`, so the overlay survives
- * page reloads. Idempotent — guard flag on `window` prevents double-install.
- *
- * Accepts either a `Page` (overlay applies to that page) or a
- * `BrowserContext` (overlay applies to every page in the context, including
- * pages opened later).
- *
- * @example
- * ```ts
- * const browser = await chromium.launch({ headless: false });
- * const context = await browser.newContext();
- * await installMouseHelper(context);
- * const page = await context.newPage();
- * // human-driven actions are now visible in the page
- * ```
- */
 declare function installMouseHelper(target: BrowserContext | Page, options?: InstallMouseHelperOptions): Promise<void>;
 
 /**
@@ -310,6 +464,65 @@ interface Human {
      * Returns a {@link ScrollResult} for assertions in tests.
      */
     scroll(target?: ScrollTarget, options?: ScrollOptions): Promise<ScrollResult>;
+    /**
+     * Pause for `ms` milliseconds. Equivalent to importing `sleep` from
+     * `@humanjs/playwright` and calling it — exposed on the Human instance
+     * so users who already have `human` in scope don't need an extra import.
+     *
+     * Not a humanized action: this is a raw `setTimeout` wait, not scaled
+     * by personality or speed mode, and no plugin events fire. Use it for
+     * generic pacing between humanized actions.
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Records `fn`'s actions. Returns a {@link Recording} you can export
+     * to mp4/webm video (`toVideo`), JSON timeline (`toTimeline`), or both.
+     *
+     * By default, frames are captured from the browser via timer-polled
+     * `page.screenshot()` — fully controllable quality, not limited by
+     * Playwright's recordVideo bitrate ceiling. Pass `{ video: false }` to
+     * skip capture entirely (timeline-only mode, zero video overhead).
+     *
+     * Plugins observe `'record'` in `beforeAction` / `afterAction` so
+     * recording shows up alongside the other primitives in observability
+     * pipelines.
+     *
+     * Single-use per session: `Recording.toVideo()` finalizes the captured
+     * frames, so calling `human.record()` twice on the same human throws.
+     *
+     * @example
+     * ```ts
+     * // Default: video + timeline
+     * const rec = await human.record(async () => {
+     *   await human.click('#login');
+     * });
+     * await rec.toVideo('demo.mp4');
+     * await rec.toTimeline('demo.json');
+     *
+     * // Timeline-only, no video overhead
+     * const rec = await human.record({ video: false }, async () => {
+     *   await human.click('#login');
+     * });
+     * await rec.toTimeline('demo.json');
+     * ```
+     */
+    record(fn: () => Promise<void>): Promise<Recording>;
+    record(options: HumanRecordOptions, fn: () => Promise<void>): Promise<Recording>;
+}
+/** Options for {@link Human.record}. */
+interface HumanRecordOptions {
+    /**
+     * Whether to capture frames for video output. Defaults to `true`.
+     * Set to `false` for timeline-only recordings (no capture loop, no
+     * temp files, no encoding overhead — `toTimeline()` still works).
+     */
+    readonly video?: boolean;
+    /**
+     * Capture quality preset. Controls per-frame JPEG quality (or PNG for
+     * lossless) AND the ffmpeg encode settings used by `toVideo()`.
+     * Defaults to `'high'`. Ignored when `video: false`.
+     */
+    readonly quality?: RecordingQuality;
 }
 /**
  * Creates a humanized session bound to a Playwright `Page`.
@@ -332,4 +545,4 @@ interface Human {
  */
 declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
 
-export { type CreateHumanOptions, type Human, type InstallMouseHelperOptions, type ReadOptions, type ReadResult, type ReadTarget, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, createHuman, installMouseHelper };
+export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ReadKind, PersonalityConfig, HumanPlugin, Point, Personality } from '@humanjs/core';
-export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions, DwellProfile, HumanAction, HumanPlugin, HumanizePathOptions, Keystroke, KnownActionType, MouseProfile, Personality, PersonalityConfig, PersonalityExtension, PlanTypingOptions, PluginContext, Point, PresetName, ReadKind, ReadingProfile, Rng, ScrollProfile, ScrollSegment, TypingProfile, applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, computeReadingDwellMs, countWords, createRng, distracted, fast, humanizePath, planScroll, planTypeKeystrokes, precise, resolvePersonality } from '@humanjs/core';
+export { ActionResult, ActionType, BezierPathOptions, ComputeReadingDwellOptions, DwellProfile, HumanAction, HumanPlugin, HumanizePathOptions, Keystroke, KnownActionType, MouseProfile, Personality, PersonalityConfig, PersonalityExtension, PlanTypingOptions, PluginContext, Point, PresetName, ReadKind, ReadingProfile, Rng, ScrollProfile, ScrollSegment, TypingProfile, applyMicroJitter, applyVelocityProfile, bezierPath, blend, careful, computeReadingDwellMs, countWords, createRng, distracted, fast, humanizePath, planScroll, planTypeKeystrokes, precise, resolvePersonality, sleep } from '@humanjs/core';
 import { Locator, BrowserContext, Page } from 'playwright';
+export { Browser, BrowserContext, BrowserContextOptions, ElementHandle, LaunchOptions, Locator, Page, chromium, firefox, webkit } from 'playwright';
 
 /**
  * What to read:
@@ -39,9 +40,10 @@ interface ReadOptions {
     /**
      * For selector/Locator targets: trace a humanized cursor path through the
      * target's bounding box while the dwell elapses, like an eye tracking
-     * lines of text. Off by default — opt in when you want the humanization
-     * signal (or when reading-time mouseover behavior matters, e.g. tooltips
-     * that activate while a real user's cursor moves over the content).
+     * lines of text. **Defaults to `true`** — "reading" implies looking, and
+     * looking implies motion. Pass `false` to skip motion when you only
+     * care about the temporal pattern (typical AI-agent use case where
+     * the cursor position is irrelevant).
      *
      * The scan path is generated by `planReadingScan` from `@humanjs/core`
      * (same deterministic-by-seed contract as the rest of the library) and
@@ -63,6 +65,183 @@ interface ReadResult {
     readonly kind: ReadKind;
 }
 
+/**
+ * A captured frame in the timer-based capture session. `tMs` is the
+ * wall-clock offset (ms) from the capture start.
+ */
+interface CapturedFrame {
+    readonly path: string;
+    readonly tMs: number;
+}
+/** Outcome of a finalized capture session. */
+interface CaptureResult {
+    readonly dir: string;
+    readonly frames: readonly CapturedFrame[];
+    readonly startedAtMs: number;
+    readonly stoppedAtMs: number;
+    readonly format: 'jpeg' | 'png';
+    readonly fps: number;
+    /**
+     * Removes the temp directory + all frames. Called by `Recording.dispose()`
+     * and by the sweep-on-exit handler — not by the exporters, which are
+     * repeatable and read the frames without consuming them. Also called
+     * directly by the error path in `human.record()` when the callback throws.
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * Encoding quality preset. Picks the per-frame capture quality + the
+ * ffmpeg encode settings used to assemble them into a video.
+ *
+ * - `'fast'` — JPEG q=85, CRF 23, preset fast (iteration)
+ * - `'standard'` — JPEG q=90, CRF 20, preset fast (balanced)
+ * - `'high'` (default) — JPEG q=95, CRF 18, preset slow, tune animation (marketing-grade)
+ * - `'lossless'` — PNG capture, CRF 12, preset veryslow (archival; huge temp files)
+ */
+type RecordingQuality = 'fast' | 'high' | 'lossless' | 'standard';
+/** ffmpeg `-preset` values, ordered from fastest to slowest. */
+type FfmpegPreset = 'fast' | 'faster' | 'medium' | 'slow' | 'slower' | 'superfast' | 'ultrafast' | 'veryfast' | 'veryslow';
+/** ffmpeg `-tune` values for libx264. */
+type FfmpegTune = 'animation' | 'fastdecode' | 'film' | 'grain' | 'stillimage' | 'zerolatency';
+/** Options for {@link Recording.toVideo}. */
+interface ToVideoOptions {
+    /** Encoding quality preset. Defaults to `'high'`. */
+    readonly quality?: RecordingQuality;
+    /** Override CRF (0–51, lower = better). Defaults to the quality preset's CRF. */
+    readonly crf?: number;
+    /** Override ffmpeg `-preset`. Defaults to the quality preset's preset. */
+    readonly preset?: FfmpegPreset;
+    /** Override ffmpeg `-tune`. Defaults to the quality preset's tune (if any). */
+    readonly tune?: FfmpegTune;
+}
+/** Options for {@link Recording.toGif}. */
+interface ToGifOptions {
+    /**
+     * Frames per second of the output GIF. Defaults to `15` — high enough for
+     * smooth motion in most renderers, low enough to keep file size sane.
+     * Renderers cap GIF playback around 50fps anyway.
+     */
+    readonly fps?: number;
+    /**
+     * Scale the GIF to this width (pixels). Height is computed to preserve
+     * aspect ratio. Omit to keep the source viewport size — but most embedded
+     * GIFs (README, PR, Slack) look fine at 640–960px and weigh a fraction.
+     */
+    readonly width?: number;
+}
+/** One action captured during a recording, as emitted in {@link Timeline.events}. */
+interface TimelineEvent {
+    readonly type: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    /** Offset (ms) from the recording start when the action began. */
+    readonly tMs: number;
+    readonly durationMs: number;
+    /** Error message, present only if the action threw. */
+    readonly error?: string;
+}
+/** Structured action timeline of a recording. */
+interface Timeline {
+    readonly version: 1;
+    readonly personality: string;
+    readonly seed: string | null;
+    readonly speed: string;
+    readonly durationMs: number;
+    readonly events: readonly TimelineEvent[];
+}
+/** Metadata passed from `human.record()` into the Recording constructor. */
+interface RecordingTimelineSource {
+    readonly personality: string;
+    readonly seed: string | null;
+    readonly speed: string;
+    readonly events: readonly TimelineEvent[];
+}
+/**
+ * A recorded window of a humanized session. Returned by `human.record(cb)`.
+ *
+ * A Recording can hold a frame capture (`hasVideo === true`) OR be
+ * timeline-only (`hasVideo === false`). `toVideo()` / `toGif()` require a
+ * capture; `toTimeline()` and `.timeline` work either way.
+ *
+ * The video exporters are repeatable and interleavable — they read the
+ * captured frames without consuming them. Calling `dispose()` is OPTIONAL:
+ * the captured-frames temp dir is also swept by a `process.on('exit')`
+ * handler installed on first use, so casual scripts can skip it entirely.
+ * Call `dispose()` (or use `await using`) when you want to release the
+ * frames proactively — long-running services, batch jobs, etc.
+ */
+declare class Recording {
+    #private;
+    constructor(capture: CaptureResult | null, windowStartMs: number, windowEndMs: number, timelineSource: RecordingTimelineSource);
+    /** Wall-clock duration of the recorded window. */
+    get durationMs(): number;
+    /** True if frames were captured during this recording. */
+    get hasVideo(): boolean;
+    /**
+     * The structured action timeline of this recording — same data that
+     * `toTimeline()` writes to disk.
+     */
+    get timeline(): Timeline;
+    /**
+     * 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.
+     */
+    toVideo(outputPath: string, options?: ToVideoOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    toGif(outputPath: string, options?: ToGifOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    toTimeline(outputPath: string): Promise<string>;
+    /**
+     * 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
+     * ```
+     */
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
 /**
  * What / where to scroll. The chosen axis (`'y'` by default, `'x'` via
  * `options.axis`) decides whether targets resolve along the vertical or
@@ -165,31 +344,6 @@ interface InstallMouseHelperOptions {
     /** Halo opacity behind the cursor. Defaults to `0.18`. */
     readonly haloOpacity?: number;
 }
-/**
- * Installs a visual cursor overlay that follows every `mousemove` on each
- * page in the target. Real synthetic motion from Playwright (e.g.
- * `human.click()`, `human.read(..., { withMotion: true })`) is *already*
- * happening — the page just doesn't render a system cursor for it. This
- * helper injects a HumanJS-styled SVG cursor that listens to mousemove
- * events and follows them, making the motion visible in headed demos and
- * screen recordings.
- *
- * Re-runs on every navigation via `addInitScript`, so the overlay survives
- * page reloads. Idempotent — guard flag on `window` prevents double-install.
- *
- * Accepts either a `Page` (overlay applies to that page) or a
- * `BrowserContext` (overlay applies to every page in the context, including
- * pages opened later).
- *
- * @example
- * ```ts
- * const browser = await chromium.launch({ headless: false });
- * const context = await browser.newContext();
- * await installMouseHelper(context);
- * const page = await context.newPage();
- * // human-driven actions are now visible in the page
- * ```
- */
 declare function installMouseHelper(target: BrowserContext | Page, options?: InstallMouseHelperOptions): Promise<void>;
 
 /**
@@ -310,6 +464,65 @@ interface Human {
      * Returns a {@link ScrollResult} for assertions in tests.
      */
     scroll(target?: ScrollTarget, options?: ScrollOptions): Promise<ScrollResult>;
+    /**
+     * Pause for `ms` milliseconds. Equivalent to importing `sleep` from
+     * `@humanjs/playwright` and calling it — exposed on the Human instance
+     * so users who already have `human` in scope don't need an extra import.
+     *
+     * Not a humanized action: this is a raw `setTimeout` wait, not scaled
+     * by personality or speed mode, and no plugin events fire. Use it for
+     * generic pacing between humanized actions.
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Records `fn`'s actions. Returns a {@link Recording} you can export
+     * to mp4/webm video (`toVideo`), JSON timeline (`toTimeline`), or both.
+     *
+     * By default, frames are captured from the browser via timer-polled
+     * `page.screenshot()` — fully controllable quality, not limited by
+     * Playwright's recordVideo bitrate ceiling. Pass `{ video: false }` to
+     * skip capture entirely (timeline-only mode, zero video overhead).
+     *
+     * Plugins observe `'record'` in `beforeAction` / `afterAction` so
+     * recording shows up alongside the other primitives in observability
+     * pipelines.
+     *
+     * Single-use per session: `Recording.toVideo()` finalizes the captured
+     * frames, so calling `human.record()` twice on the same human throws.
+     *
+     * @example
+     * ```ts
+     * // Default: video + timeline
+     * const rec = await human.record(async () => {
+     *   await human.click('#login');
+     * });
+     * await rec.toVideo('demo.mp4');
+     * await rec.toTimeline('demo.json');
+     *
+     * // Timeline-only, no video overhead
+     * const rec = await human.record({ video: false }, async () => {
+     *   await human.click('#login');
+     * });
+     * await rec.toTimeline('demo.json');
+     * ```
+     */
+    record(fn: () => Promise<void>): Promise<Recording>;
+    record(options: HumanRecordOptions, fn: () => Promise<void>): Promise<Recording>;
+}
+/** Options for {@link Human.record}. */
+interface HumanRecordOptions {
+    /**
+     * Whether to capture frames for video output. Defaults to `true`.
+     * Set to `false` for timeline-only recordings (no capture loop, no
+     * temp files, no encoding overhead — `toTimeline()` still works).
+     */
+    readonly video?: boolean;
+    /**
+     * Capture quality preset. Controls per-frame JPEG quality (or PNG for
+     * lossless) AND the ffmpeg encode settings used by `toVideo()`.
+     * Defaults to `'high'`. Ignored when `video: false`.
+     */
+    readonly quality?: RecordingQuality;
 }
 /**
  * Creates a humanized session bound to a Playwright `Page`.
@@ -332,4 +545,4 @@ interface Human {
  */
 declare function createHuman(page: Page, options?: CreateHumanOptions): Promise<Human>;
 
-export { type CreateHumanOptions, type Human, type InstallMouseHelperOptions, type ReadOptions, type ReadResult, type ReadTarget, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, createHuman, installMouseHelper };
+export { type CreateHumanOptions, type FfmpegPreset, type FfmpegTune, type Human, type HumanRecordOptions, type InstallMouseHelperOptions, type ReadOptions, type ReadResult, type ReadTarget, Recording, type RecordingQuality, type ScrollOptions, type ScrollResult, type ScrollTarget, type Speed, type Timeline, type TimelineEvent, type ToGifOptions, type ToVideoOptions, createHuman, installMouseHelper };