@humanjs/recorder 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gonzalo Muñoz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @humanjs/recorder
+
+One-call session recording for [HumanJS](https://humanjs.dev) — turn a humanized Playwright session into an mp4, an animated GIF, a structured JSON timeline, or any combination.
+
+## Install
+
+```bash
+pnpm add @humanjs/recorder @humanjs/playwright playwright
+```
+
+`@humanjs/playwright` bundles `ffmpeg-static`, so no system ffmpeg install is required.
+
+## Quick start
+
+```ts
+import { record } from '@humanjs/recorder';
+
+// Record a session to mp4
+await record({ output: 'demo.mp4' }, async (human) => {
+  await human.click('a');
+  await human.type('#search', 'humanjs');
+});
+
+// Timeline-only — no video overhead
+const rec = await record(async (human) => {
+  await human.click('#login');
+});
+await rec.toTimeline('actions.json');
+```
+
+`record()` launches a browser, opens a page, creates a humanized session, runs the callback, manages the entire lifecycle — and returns a `Recording` you can export to any supported format.
+
+## API shape
+
+Two overloads — pass options when you have them, skip them when you don't:
+
+```ts
+// No options needed
+const rec = await record(async (human) => { ... });
+
+// With options
+const rec = await record({ output: 'demo.mp4', personality: 'careful' }, async (human) => { ... });
+```
+
+The returned `Recording` has:
+
+| | |
+|---|---|
+| `rec.toVideo(path, options?)` | Write an mp4 or webm. Repeatable. |
+| `rec.toGif(path, options?)` | Write an animated GIF (palette-optimized, defaults to 15fps). Repeatable. |
+| `rec.toTimeline(path)` | Write the structured JSON timeline. Repeatable. |
+| `rec.timeline` | Read the in-memory `Timeline` object. |
+| `rec.durationMs` | Wall-clock duration of the recorded window. |
+| `rec.hasVideo` | True if frames were captured (i.e. `output` was set). |
+| `rec.dispose()` | *Optional.* Release the captured-frames temp directory early — otherwise a sweep-on-exit handler cleans it when the process ends. After this, `toVideo` / `toGif` throw; `toTimeline` still works. Idempotent. |
+
+The exporters are **repeatable and interleavable** — they read the captured frames, they don't consume them. If `output` was passed to `record()`, the matching exporter has already run for you, but you can still call any other exporter (or call the same one again to a different path) on the returned recording. Want mp4 and GIF from the same recording? Just do both:
+
+```ts
+const rec = await record({ output: 'demo.mp4' }, async (human) => { ... });
+await rec.toGif('demo.gif', { width: 720 });
+await rec.toTimeline('demo.json');
+// Done. No explicit cleanup needed for one-shot scripts.
+```
+
+Captured frames live in a temp dir under `os.tmpdir()`. A `process.on('exit')` handler installed on first use sweeps any un-disposed frame dirs, so casual scripts don't have to think about lifecycle. For long-running services or anywhere you want predictable disk usage, call `await rec.dispose()` (idempotent) or use `await using rec = await record(...)` (TypeScript ≥ 5.2 / Node ≥ 20.4).
+
+## Options
+
+```ts
+await record(
+  {
+    output: 'demo.mp4',          // .mp4 / .webm / .gif — omit to skip video entirely
+    quality: 'high',             // 'fast' | 'standard' | 'high' (default) | 'lossless'
+    url: 'https://example.com',  // optional — navigate before the callback
+    personality: 'careful',      // any PersonalityConfig
+    seed: 'session-42',          // deterministic when set
+    viewport: { width: 1920, height: 1080 },
+    headless: false,             // defaults false so you can watch the recording
+    cursor: true,                // auto-install visible cursor overlay (default true)
+    launch: { args: ['--no-sandbox'] },  // forwarded to chromium.launch()
+    context: { locale: 'en-US' },         // forwarded to browser.newContext()
+  },
+  async (human, page) => {
+    // human is the @humanjs/playwright session — all primitives available
+    // page is the underlying Playwright Page, in case you need it
+    await human.click('#start');
+    await human.scroll('#features');
+    await human.read('#hero p');
+  },
+);
+```
+
+**No-video mode**: omit `output` entirely (or call `record(fn)` with no options). No screenshot polling, no temp files, no encoding overhead. The structured timeline is still captured.
+
+## Quality presets
+
+Pick the preset that matches the recording's purpose:
+
+| Preset | Viewport | Capture | CRF | ffmpeg preset | tune | Use case |
+|---|---|---|---|---|---|---|
+| `'fast'` | 1280×720 | JPEG q=85 | 23 | `fast` | — | Iteration, throw-away recordings |
+| `'standard'` | 1920×1080 | JPEG q=90 | 20 | `fast` | — | CI dashboards, casual demos |
+| **`'high'`** (default) | 1920×1080 | JPEG q=95 | 18 | `slow` | `animation` | Marketing, tutorials, portfolio output |
+| `'lossless'` | 1920×1080 | PNG | 12 | `veryslow` | `animation` | Archival, edit source |
+
+Individual encoding knobs (`crf`, `preset`, `tune`) are exposed through `@humanjs/playwright`'s `Recording.toVideo()` for advanced use — see [`@humanjs/playwright`](../playwright#recording).
+
+## When to use `record()` vs `human.record()`
+
+| Use this | When |
+|---|---|
+| **`record()` from `@humanjs/recorder`** | You want lifecycle managed for you. The returned `Recording` still gives full programmatic access — `toTimeline()`, in-memory `.timeline`, `.durationMs`. |
+| **`human.record(cb)` from `@humanjs/playwright`** | You already have a Playwright setup, need multi-page flows, or want to record a slice of a longer session. |
+
+Both paths produce identical Recording objects — `record()` is a thin wrapper around `human.record()` plus lifecycle management.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,75 @@
+'use strict';
+
+var path = require('path');
+var playwright = require('@humanjs/playwright');
+
+// src/record/index.ts
+var QUALITY_BROWSER_PRESETS = {
+  // 720p source — small files, fast encoding, good for iteration.
+  fast: { viewport: { width: 1280, height: 720 } },
+  // 1080p source — balanced default for tests and dashboards.
+  standard: { viewport: { width: 1920, height: 1080 } },
+  // 1080p source, visually-lossless encoding (slow preset + animation tune).
+  // Recommended for marketing / portfolio output.
+  high: { viewport: { width: 1920, height: 1080 } },
+  // 1080p source, archival-quality encoding (very slow, low CRF).
+  lossless: { viewport: { width: 1920, height: 1080 } }
+};
+async function record(optionsOrFn, maybeFn) {
+  const [options, fn] = typeof optionsOrFn === "function" ? [{}, optionsOrFn] : [optionsOrFn, maybeFn];
+  const {
+    output,
+    quality,
+    url,
+    viewport,
+    headless,
+    launch,
+    context,
+    cursor,
+    ...createHumanOptions
+  } = options;
+  const resolvedQuality = quality ?? "high";
+  const browserPreset = QUALITY_BROWSER_PRESETS[resolvedQuality];
+  const resolvedViewport = viewport ?? context?.viewport ?? browserPreset.viewport;
+  const wantsCapture = output !== void 0;
+  const browser = await playwright.chromium.launch({
+    ...launch,
+    headless: headless ?? false
+  });
+  try {
+    const browserContext = await browser.newContext({
+      ...context,
+      viewport: resolvedViewport
+    });
+    try {
+      if (cursor !== false) {
+        const cursorOptions = typeof cursor === "object" ? cursor : void 0;
+        await playwright.installMouseHelper(browserContext, cursorOptions);
+      }
+      const page = await browserContext.newPage();
+      if (url) await page.goto(url);
+      const human = await playwright.createHuman(page, createHumanOptions);
+      const recording = await human.record(
+        { video: wantsCapture, quality: resolvedQuality },
+        () => fn(human, page)
+      );
+      if (wantsCapture && output) {
+        const ext = path.extname(output).toLowerCase();
+        if (ext === ".gif") {
+          await recording.toGif(output);
+        } else {
+          await recording.toVideo(output, { quality: resolvedQuality });
+        }
+      }
+      return recording;
+    } finally {
+      await browserContext.close().catch(() => void 0);
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+exports.record = record;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/record/index.ts"],"names":["chromium","installMouseHelper","createHuman","extname"],"mappings":"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","file":"index.cjs","sourcesContent":["import { extname } from 'node:path';\nimport {\n  type BrowserContextOptions,\n  type CreateHumanOptions,\n  chromium,\n  createHuman,\n  type Human,\n  type InstallMouseHelperOptions,\n  installMouseHelper,\n  type LaunchOptions,\n  type Page,\n  type Recording,\n  type RecordingQuality,\n} from '@humanjs/playwright';\n\ninterface QualityBrowserPreset {\n  readonly viewport: { readonly width: number; readonly height: number };\n}\n\nconst QUALITY_BROWSER_PRESETS: Record<RecordingQuality, QualityBrowserPreset> = {\n  // 720p source — small files, fast encoding, good for iteration.\n  fast: { viewport: { width: 1280, height: 720 } },\n  // 1080p source — balanced default for tests and dashboards.\n  standard: { viewport: { width: 1920, height: 1080 } },\n  // 1080p source, visually-lossless encoding (slow preset + animation tune).\n  // Recommended for marketing / portfolio output.\n  high: { viewport: { width: 1920, height: 1080 } },\n  // 1080p source, archival-quality encoding (very slow, low CRF).\n  lossless: { viewport: { width: 1920, height: 1080 } },\n};\n\n/**\n * Options for {@link record}. Most fields are passed straight through to\n * Playwright's `chromium.launch()` and `browser.newContext()` so a one-call\n * recording can configure anything a full Playwright setup could.\n */\nexport interface RecordOptions extends CreateHumanOptions {\n  /**\n   * Output path. Extension determines format — `.mp4` / `.webm` for video,\n   * or `.gif` for an animated GIF (palette-optimized, defaults to 15fps).\n   * Omit to skip capture entirely; the returned {@link Recording} still has\n   * the structured action timeline via `.toTimeline()` / `.timeline`.\n   */\n  readonly output?: string;\n  /**\n   * Quality preset. Picks both source viewport and ffmpeg encoding settings.\n   * Defaults to `'high'` (visually-lossless 1080p).\n   *\n   * - `'fast'`: 720p, CRF 23, preset fast\n   * - `'standard'`: 1080p, CRF 20, preset fast\n   * - `'high'` (default): 1080p, CRF 18, preset slow, tune animation\n   * - `'lossless'`: 1080p, CRF 12, preset veryslow, tune animation\n   */\n  readonly quality?: RecordingQuality;\n  /** Optional URL to navigate to before the callback runs. */\n  readonly url?: string;\n  /** Viewport dimensions. Overrides the quality preset's viewport. */\n  readonly viewport?: { readonly width: number; readonly height: number };\n  /** Run headless. Defaults to `false` so users can watch the recording happen. */\n  readonly headless?: boolean;\n  /** Forwarded to `chromium.launch()` (alongside `headless`). */\n  readonly launch?: LaunchOptions;\n  /** Forwarded to `browser.newContext()` (alongside `viewport`). */\n  readonly context?: BrowserContextOptions;\n  /**\n   * Install the HumanJS visible cursor overlay so recorded videos show\n   * mouse motion — Playwright's synthetic mouse doesn't render a cursor\n   * by itself, so without this the recording would look like text and\n   * UI changing on their own.\n   *\n   * - `true` (default): install with default styling (HumanJS amber, 22px)\n   * - `false`: don't install — the user will install their own, or the\n   *   recording intentionally has no visible cursor\n   * - {@link InstallMouseHelperOptions}: install with custom color / size /\n   *   click-ripple / halo settings\n   *\n   * The helper is installed on the context via `addInitScript` + a\n   * DOMContentLoaded listener, so it persists across `page.setContent()`\n   * and navigation inside the callback.\n   */\n  readonly cursor?: boolean | InstallMouseHelperOptions;\n}\n\n/** The callback shape both overloads of {@link record} accept. */\nexport type RecordCallback = (human: Human, page: Page) => Promise<void>;\n\n/**\n * One-call session recording. Launches a browser, opens a page, creates a\n * humanized session, runs `fn`, and returns a {@link Recording} you can\n * export to video, JSON timeline, or read in-memory.\n *\n * If `options.output` is set, the output file is written to that path before\n * `record()` resolves — extension dispatches to `toVideo` (`.mp4` / `.webm`)\n * or `toGif` (`.gif`). The returned Recording is still useful for additional\n * exports via `toVideo` / `toGif` / `toTimeline` (all repeatable). If\n * `output` is omitted, frame capture is skipped entirely (no encoding\n * overhead) and only the timeline is captured.\n *\n * @example\n * ```ts\n * // Video + timeline\n * const rec = await record({ output: 'demo.mp4' }, async (human) => {\n *   await human.click('#login');\n * });\n * await rec.toTimeline('demo.json');\n * console.log(rec.durationMs, rec.timeline.events.length);\n * ```\n *\n * @example\n * ```ts\n * // Timeline only, no video overhead\n * const rec = await record(async (human) => {\n *   await human.click('#login');\n * });\n * await rec.toTimeline('demo.json');\n * ```\n *\n * For multi-page flows or recording a slice of a larger session, use\n * `human.record()` from `@humanjs/playwright` directly.\n */\nexport function record(fn: RecordCallback): Promise<Recording>;\nexport function record(options: RecordOptions, fn: RecordCallback): Promise<Recording>;\nexport async function record(\n  optionsOrFn: RecordCallback | RecordOptions,\n  maybeFn?: RecordCallback,\n): Promise<Recording> {\n  const [options, fn] =\n    typeof optionsOrFn === 'function'\n      ? [{} as RecordOptions, optionsOrFn]\n      : [optionsOrFn, maybeFn as RecordCallback];\n\n  const {\n    output,\n    quality,\n    url,\n    viewport,\n    headless,\n    launch,\n    context,\n    cursor,\n    ...createHumanOptions\n  } = options;\n\n  const resolvedQuality: RecordingQuality = quality ?? 'high';\n  const browserPreset = QUALITY_BROWSER_PRESETS[resolvedQuality];\n  const resolvedViewport = viewport ?? context?.viewport ?? browserPreset.viewport;\n  const wantsCapture = output !== undefined;\n\n  const browser = await chromium.launch({\n    ...launch,\n    headless: headless ?? false,\n  });\n  try {\n    const browserContext = await browser.newContext({\n      ...context,\n      viewport: resolvedViewport,\n    });\n    try {\n      // Install the visible-cursor overlay before any page is created so\n      // the addInitScript runs on the initial page render — and on any\n      // page.setContent() inside the callback too.\n      if (cursor !== false) {\n        const cursorOptions = typeof cursor === 'object' ? cursor : undefined;\n        await installMouseHelper(browserContext, cursorOptions);\n      }\n\n      const page = await browserContext.newPage();\n      if (url) await page.goto(url);\n\n      const human = await createHuman(page, createHumanOptions);\n\n      // Capture runs only when the caller asked for an output file — saves\n      // the screenshot + disk-write overhead for timeline-only recordings.\n      const recording = await human.record({ video: wantsCapture, quality: resolvedQuality }, () =>\n        fn(human, page),\n      );\n\n      if (wantsCapture && output) {\n        // Dispatch by extension: .gif goes through the GIF exporter (which\n        // ignores `quality` — GIF doesn't have a CRF concept), everything\n        // else flows into the mp4/webm encoder with the chosen preset.\n        const ext = extname(output).toLowerCase();\n        if (ext === '.gif') {\n          await recording.toGif(output);\n        } else {\n          await recording.toVideo(output, { quality: resolvedQuality });\n        }\n      }\n\n      return recording;\n    } finally {\n      await browserContext.close().catch(() => undefined);\n    }\n  } finally {\n    await browser.close();\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,97 @@
+import { Human, Page, CreateHumanOptions, RecordingQuality, LaunchOptions, BrowserContextOptions, InstallMouseHelperOptions, Recording } from '@humanjs/playwright';
+export { Recording } from '@humanjs/playwright';
+
+/**
+ * Options for {@link record}. Most fields are passed straight through to
+ * Playwright's `chromium.launch()` and `browser.newContext()` so a one-call
+ * recording can configure anything a full Playwright setup could.
+ */
+interface RecordOptions extends CreateHumanOptions {
+    /**
+     * Output path. Extension determines format — `.mp4` / `.webm` for video,
+     * or `.gif` for an animated GIF (palette-optimized, defaults to 15fps).
+     * Omit to skip capture entirely; the returned {@link Recording} still has
+     * the structured action timeline via `.toTimeline()` / `.timeline`.
+     */
+    readonly output?: string;
+    /**
+     * Quality preset. Picks both source viewport and ffmpeg encoding settings.
+     * Defaults to `'high'` (visually-lossless 1080p).
+     *
+     * - `'fast'`: 720p, CRF 23, preset fast
+     * - `'standard'`: 1080p, CRF 20, preset fast
+     * - `'high'` (default): 1080p, CRF 18, preset slow, tune animation
+     * - `'lossless'`: 1080p, CRF 12, preset veryslow, tune animation
+     */
+    readonly quality?: RecordingQuality;
+    /** Optional URL to navigate to before the callback runs. */
+    readonly url?: string;
+    /** Viewport dimensions. Overrides the quality preset's viewport. */
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Run headless. Defaults to `false` so users can watch the recording happen. */
+    readonly headless?: boolean;
+    /** Forwarded to `chromium.launch()` (alongside `headless`). */
+    readonly launch?: LaunchOptions;
+    /** Forwarded to `browser.newContext()` (alongside `viewport`). */
+    readonly context?: BrowserContextOptions;
+    /**
+     * Install the HumanJS visible cursor overlay so recorded videos show
+     * mouse motion — Playwright's synthetic mouse doesn't render a cursor
+     * by itself, so without this the recording would look like text and
+     * UI changing on their own.
+     *
+     * - `true` (default): install with default styling (HumanJS amber, 22px)
+     * - `false`: don't install — the user will install their own, or the
+     *   recording intentionally has no visible cursor
+     * - {@link InstallMouseHelperOptions}: install with custom color / size /
+     *   click-ripple / halo settings
+     *
+     * The helper is installed on the context via `addInitScript` + a
+     * DOMContentLoaded listener, so it persists across `page.setContent()`
+     * and navigation inside the callback.
+     */
+    readonly cursor?: boolean | InstallMouseHelperOptions;
+}
+/** The callback shape both overloads of {@link record} accept. */
+type RecordCallback = (human: Human, page: Page) => Promise<void>;
+/**
+ * One-call session recording. Launches a browser, opens a page, creates a
+ * humanized session, runs `fn`, and returns a {@link Recording} you can
+ * export to video, JSON timeline, or read in-memory.
+ *
+ * If `options.output` is set, the output file is written to that path before
+ * `record()` resolves — extension dispatches to `toVideo` (`.mp4` / `.webm`)
+ * or `toGif` (`.gif`). The returned Recording is still useful for additional
+ * exports via `toVideo` / `toGif` / `toTimeline` (all repeatable). If
+ * `output` is omitted, frame capture is skipped entirely (no encoding
+ * overhead) and only the timeline is captured.
+ *
+ * @example
+ * ```ts
+ * // Video + timeline
+ * const rec = await record({ output: 'demo.mp4' }, async (human) => {
+ *   await human.click('#login');
+ * });
+ * await rec.toTimeline('demo.json');
+ * console.log(rec.durationMs, rec.timeline.events.length);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Timeline only, no video overhead
+ * const rec = await record(async (human) => {
+ *   await human.click('#login');
+ * });
+ * await rec.toTimeline('demo.json');
+ * ```
+ *
+ * For multi-page flows or recording a slice of a larger session, use
+ * `human.record()` from `@humanjs/playwright` directly.
+ */
+declare function record(fn: RecordCallback): Promise<Recording>;
+declare function record(options: RecordOptions, fn: RecordCallback): Promise<Recording>;
+
+export { type RecordCallback, type RecordOptions, record };

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { Human, Page, CreateHumanOptions, RecordingQuality, LaunchOptions, BrowserContextOptions, InstallMouseHelperOptions, Recording } from '@humanjs/playwright';
+export { Recording } from '@humanjs/playwright';
+
+/**
+ * Options for {@link record}. Most fields are passed straight through to
+ * Playwright's `chromium.launch()` and `browser.newContext()` so a one-call
+ * recording can configure anything a full Playwright setup could.
+ */
+interface RecordOptions extends CreateHumanOptions {
+    /**
+     * Output path. Extension determines format — `.mp4` / `.webm` for video,
+     * or `.gif` for an animated GIF (palette-optimized, defaults to 15fps).
+     * Omit to skip capture entirely; the returned {@link Recording} still has
+     * the structured action timeline via `.toTimeline()` / `.timeline`.
+     */
+    readonly output?: string;
+    /**
+     * Quality preset. Picks both source viewport and ffmpeg encoding settings.
+     * Defaults to `'high'` (visually-lossless 1080p).
+     *
+     * - `'fast'`: 720p, CRF 23, preset fast
+     * - `'standard'`: 1080p, CRF 20, preset fast
+     * - `'high'` (default): 1080p, CRF 18, preset slow, tune animation
+     * - `'lossless'`: 1080p, CRF 12, preset veryslow, tune animation
+     */
+    readonly quality?: RecordingQuality;
+    /** Optional URL to navigate to before the callback runs. */
+    readonly url?: string;
+    /** Viewport dimensions. Overrides the quality preset's viewport. */
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Run headless. Defaults to `false` so users can watch the recording happen. */
+    readonly headless?: boolean;
+    /** Forwarded to `chromium.launch()` (alongside `headless`). */
+    readonly launch?: LaunchOptions;
+    /** Forwarded to `browser.newContext()` (alongside `viewport`). */
+    readonly context?: BrowserContextOptions;
+    /**
+     * Install the HumanJS visible cursor overlay so recorded videos show
+     * mouse motion — Playwright's synthetic mouse doesn't render a cursor
+     * by itself, so without this the recording would look like text and
+     * UI changing on their own.
+     *
+     * - `true` (default): install with default styling (HumanJS amber, 22px)
+     * - `false`: don't install — the user will install their own, or the
+     *   recording intentionally has no visible cursor
+     * - {@link InstallMouseHelperOptions}: install with custom color / size /
+     *   click-ripple / halo settings
+     *
+     * The helper is installed on the context via `addInitScript` + a
+     * DOMContentLoaded listener, so it persists across `page.setContent()`
+     * and navigation inside the callback.
+     */
+    readonly cursor?: boolean | InstallMouseHelperOptions;
+}
+/** The callback shape both overloads of {@link record} accept. */
+type RecordCallback = (human: Human, page: Page) => Promise<void>;
+/**
+ * One-call session recording. Launches a browser, opens a page, creates a
+ * humanized session, runs `fn`, and returns a {@link Recording} you can
+ * export to video, JSON timeline, or read in-memory.
+ *
+ * If `options.output` is set, the output file is written to that path before
+ * `record()` resolves — extension dispatches to `toVideo` (`.mp4` / `.webm`)
+ * or `toGif` (`.gif`). The returned Recording is still useful for additional
+ * exports via `toVideo` / `toGif` / `toTimeline` (all repeatable). If
+ * `output` is omitted, frame capture is skipped entirely (no encoding
+ * overhead) and only the timeline is captured.
+ *
+ * @example
+ * ```ts
+ * // Video + timeline
+ * const rec = await record({ output: 'demo.mp4' }, async (human) => {
+ *   await human.click('#login');
+ * });
+ * await rec.toTimeline('demo.json');
+ * console.log(rec.durationMs, rec.timeline.events.length);
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Timeline only, no video overhead
+ * const rec = await record(async (human) => {
+ *   await human.click('#login');
+ * });
+ * await rec.toTimeline('demo.json');
+ * ```
+ *
+ * For multi-page flows or recording a slice of a larger session, use
+ * `human.record()` from `@humanjs/playwright` directly.
+ */
+declare function record(fn: RecordCallback): Promise<Recording>;
+declare function record(options: RecordOptions, fn: RecordCallback): Promise<Recording>;
+
+export { type RecordCallback, type RecordOptions, record };

package/dist/index.js

@@ -0,0 +1,73 @@
+import { extname } from 'path';
+import { chromium, installMouseHelper, createHuman } from '@humanjs/playwright';
+
+// src/record/index.ts
+var QUALITY_BROWSER_PRESETS = {
+  // 720p source — small files, fast encoding, good for iteration.
+  fast: { viewport: { width: 1280, height: 720 } },
+  // 1080p source — balanced default for tests and dashboards.
+  standard: { viewport: { width: 1920, height: 1080 } },
+  // 1080p source, visually-lossless encoding (slow preset + animation tune).
+  // Recommended for marketing / portfolio output.
+  high: { viewport: { width: 1920, height: 1080 } },
+  // 1080p source, archival-quality encoding (very slow, low CRF).
+  lossless: { viewport: { width: 1920, height: 1080 } }
+};
+async function record(optionsOrFn, maybeFn) {
+  const [options, fn] = typeof optionsOrFn === "function" ? [{}, optionsOrFn] : [optionsOrFn, maybeFn];
+  const {
+    output,
+    quality,
+    url,
+    viewport,
+    headless,
+    launch,
+    context,
+    cursor,
+    ...createHumanOptions
+  } = options;
+  const resolvedQuality = quality ?? "high";
+  const browserPreset = QUALITY_BROWSER_PRESETS[resolvedQuality];
+  const resolvedViewport = viewport ?? context?.viewport ?? browserPreset.viewport;
+  const wantsCapture = output !== void 0;
+  const browser = await chromium.launch({
+    ...launch,
+    headless: headless ?? false
+  });
+  try {
+    const browserContext = await browser.newContext({
+      ...context,
+      viewport: resolvedViewport
+    });
+    try {
+      if (cursor !== false) {
+        const cursorOptions = typeof cursor === "object" ? cursor : void 0;
+        await installMouseHelper(browserContext, cursorOptions);
+      }
+      const page = await browserContext.newPage();
+      if (url) await page.goto(url);
+      const human = await createHuman(page, createHumanOptions);
+      const recording = await human.record(
+        { video: wantsCapture, quality: resolvedQuality },
+        () => fn(human, page)
+      );
+      if (wantsCapture && output) {
+        const ext = extname(output).toLowerCase();
+        if (ext === ".gif") {
+          await recording.toGif(output);
+        } else {
+          await recording.toVideo(output, { quality: resolvedQuality });
+        }
+      }
+      return recording;
+    } finally {
+      await browserContext.close().catch(() => void 0);
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+export { record };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/record/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { extname } from 'node:path';\nimport {\n  type BrowserContextOptions,\n  type CreateHumanOptions,\n  chromium,\n  createHuman,\n  type Human,\n  type InstallMouseHelperOptions,\n  installMouseHelper,\n  type LaunchOptions,\n  type Page,\n  type Recording,\n  type RecordingQuality,\n} from '@humanjs/playwright';\n\ninterface QualityBrowserPreset {\n  readonly viewport: { readonly width: number; readonly height: number };\n}\n\nconst QUALITY_BROWSER_PRESETS: Record<RecordingQuality, QualityBrowserPreset> = {\n  // 720p source — small files, fast encoding, good for iteration.\n  fast: { viewport: { width: 1280, height: 720 } },\n  // 1080p source — balanced default for tests and dashboards.\n  standard: { viewport: { width: 1920, height: 1080 } },\n  // 1080p source, visually-lossless encoding (slow preset + animation tune).\n  // Recommended for marketing / portfolio output.\n  high: { viewport: { width: 1920, height: 1080 } },\n  // 1080p source, archival-quality encoding (very slow, low CRF).\n  lossless: { viewport: { width: 1920, height: 1080 } },\n};\n\n/**\n * Options for {@link record}. Most fields are passed straight through to\n * Playwright's `chromium.launch()` and `browser.newContext()` so a one-call\n * recording can configure anything a full Playwright setup could.\n */\nexport interface RecordOptions extends CreateHumanOptions {\n  /**\n   * Output path. Extension determines format — `.mp4` / `.webm` for video,\n   * or `.gif` for an animated GIF (palette-optimized, defaults to 15fps).\n   * Omit to skip capture entirely; the returned {@link Recording} still has\n   * the structured action timeline via `.toTimeline()` / `.timeline`.\n   */\n  readonly output?: string;\n  /**\n   * Quality preset. Picks both source viewport and ffmpeg encoding settings.\n   * Defaults to `'high'` (visually-lossless 1080p).\n   *\n   * - `'fast'`: 720p, CRF 23, preset fast\n   * - `'standard'`: 1080p, CRF 20, preset fast\n   * - `'high'` (default): 1080p, CRF 18, preset slow, tune animation\n   * - `'lossless'`: 1080p, CRF 12, preset veryslow, tune animation\n   */\n  readonly quality?: RecordingQuality;\n  /** Optional URL to navigate to before the callback runs. */\n  readonly url?: string;\n  /** Viewport dimensions. Overrides the quality preset's viewport. */\n  readonly viewport?: { readonly width: number; readonly height: number };\n  /** Run headless. Defaults to `false` so users can watch the recording happen. */\n  readonly headless?: boolean;\n  /** Forwarded to `chromium.launch()` (alongside `headless`). */\n  readonly launch?: LaunchOptions;\n  /** Forwarded to `browser.newContext()` (alongside `viewport`). */\n  readonly context?: BrowserContextOptions;\n  /**\n   * Install the HumanJS visible cursor overlay so recorded videos show\n   * mouse motion — Playwright's synthetic mouse doesn't render a cursor\n   * by itself, so without this the recording would look like text and\n   * UI changing on their own.\n   *\n   * - `true` (default): install with default styling (HumanJS amber, 22px)\n   * - `false`: don't install — the user will install their own, or the\n   *   recording intentionally has no visible cursor\n   * - {@link InstallMouseHelperOptions}: install with custom color / size /\n   *   click-ripple / halo settings\n   *\n   * The helper is installed on the context via `addInitScript` + a\n   * DOMContentLoaded listener, so it persists across `page.setContent()`\n   * and navigation inside the callback.\n   */\n  readonly cursor?: boolean | InstallMouseHelperOptions;\n}\n\n/** The callback shape both overloads of {@link record} accept. */\nexport type RecordCallback = (human: Human, page: Page) => Promise<void>;\n\n/**\n * One-call session recording. Launches a browser, opens a page, creates a\n * humanized session, runs `fn`, and returns a {@link Recording} you can\n * export to video, JSON timeline, or read in-memory.\n *\n * If `options.output` is set, the output file is written to that path before\n * `record()` resolves — extension dispatches to `toVideo` (`.mp4` / `.webm`)\n * or `toGif` (`.gif`). The returned Recording is still useful for additional\n * exports via `toVideo` / `toGif` / `toTimeline` (all repeatable). If\n * `output` is omitted, frame capture is skipped entirely (no encoding\n * overhead) and only the timeline is captured.\n *\n * @example\n * ```ts\n * // Video + timeline\n * const rec = await record({ output: 'demo.mp4' }, async (human) => {\n *   await human.click('#login');\n * });\n * await rec.toTimeline('demo.json');\n * console.log(rec.durationMs, rec.timeline.events.length);\n * ```\n *\n * @example\n * ```ts\n * // Timeline only, no video overhead\n * const rec = await record(async (human) => {\n *   await human.click('#login');\n * });\n * await rec.toTimeline('demo.json');\n * ```\n *\n * For multi-page flows or recording a slice of a larger session, use\n * `human.record()` from `@humanjs/playwright` directly.\n */\nexport function record(fn: RecordCallback): Promise<Recording>;\nexport function record(options: RecordOptions, fn: RecordCallback): Promise<Recording>;\nexport async function record(\n  optionsOrFn: RecordCallback | RecordOptions,\n  maybeFn?: RecordCallback,\n): Promise<Recording> {\n  const [options, fn] =\n    typeof optionsOrFn === 'function'\n      ? [{} as RecordOptions, optionsOrFn]\n      : [optionsOrFn, maybeFn as RecordCallback];\n\n  const {\n    output,\n    quality,\n    url,\n    viewport,\n    headless,\n    launch,\n    context,\n    cursor,\n    ...createHumanOptions\n  } = options;\n\n  const resolvedQuality: RecordingQuality = quality ?? 'high';\n  const browserPreset = QUALITY_BROWSER_PRESETS[resolvedQuality];\n  const resolvedViewport = viewport ?? context?.viewport ?? browserPreset.viewport;\n  const wantsCapture = output !== undefined;\n\n  const browser = await chromium.launch({\n    ...launch,\n    headless: headless ?? false,\n  });\n  try {\n    const browserContext = await browser.newContext({\n      ...context,\n      viewport: resolvedViewport,\n    });\n    try {\n      // Install the visible-cursor overlay before any page is created so\n      // the addInitScript runs on the initial page render — and on any\n      // page.setContent() inside the callback too.\n      if (cursor !== false) {\n        const cursorOptions = typeof cursor === 'object' ? cursor : undefined;\n        await installMouseHelper(browserContext, cursorOptions);\n      }\n\n      const page = await browserContext.newPage();\n      if (url) await page.goto(url);\n\n      const human = await createHuman(page, createHumanOptions);\n\n      // Capture runs only when the caller asked for an output file — saves\n      // the screenshot + disk-write overhead for timeline-only recordings.\n      const recording = await human.record({ video: wantsCapture, quality: resolvedQuality }, () =>\n        fn(human, page),\n      );\n\n      if (wantsCapture && output) {\n        // Dispatch by extension: .gif goes through the GIF exporter (which\n        // ignores `quality` — GIF doesn't have a CRF concept), everything\n        // else flows into the mp4/webm encoder with the chosen preset.\n        const ext = extname(output).toLowerCase();\n        if (ext === '.gif') {\n          await recording.toGif(output);\n        } else {\n          await recording.toVideo(output, { quality: resolvedQuality });\n        }\n      }\n\n      return recording;\n    } finally {\n      await browserContext.close().catch(() => undefined);\n    }\n  } finally {\n    await browser.close();\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@humanjs/recorder",
+  "version": "0.1.0",
+  "description": "One-call session recording for HumanJS — capture a humanized Playwright session as mp4, webm, gif, or a structured JSON timeline.",
+  "keywords": [
+    "humanjs",
+    "playwright",
+    "recorder",
+    "video",
+    "mp4",
+    "webm",
+    "gif",
+    "humanize",
+    "browser-automation"
+  ],
+  "author": "Gonzalo Muñoz <toti@eventurex.com.ar>",
+  "license": "MIT",
+  "homepage": "https://humanjs.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/totigm/humanjs.git",
+    "directory": "packages/recorder"
+  },
+  "bugs": "https://github.com/totigm/humanjs/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@humanjs/playwright": "0.4.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0"
+  },
+  "devDependencies": {
+    "playwright": "^1.60.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:integration": "vitest run -c vitest.integration.config.ts",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "clean": "rm -rf dist .turbo"
+  }
+}