npm - @humanjs/recorder - Versions diffs - 0.1.1 → 0.2.0 - Mend

@humanjs/recorder 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,5 +1,14 @@
 # @humanjs/recorder
+<p>
+  <a href="https://www.npmjs.com/package/@humanjs/recorder"><img alt="npm" src="https://img.shields.io/npm/v/@humanjs/recorder"></a>
+  <a href="https://www.npmjs.com/package/@humanjs/recorder"><img alt="downloads" src="https://img.shields.io/npm/dt/@humanjs/recorder"></a>
+  <a href="https://github.com/totigm/humanjs"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-totigm%2Fhumanjs-181717?logo=github"></a>
+  <a href="https://github.com/totigm/humanjs/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/totigm/humanjs/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/totigm/humanjs/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@humanjs/recorder"></a>
+  <a href="https://humanjs.dev"><img alt="docs" src="https://img.shields.io/badge/docs-humanjs.dev-emerald"></a>
+</p>
 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
@@ -75,9 +84,12 @@ await record(
     url: 'https://example.com',  // optional — navigate before the callback
     personality: 'careful',      // any PersonalityConfig
     seed: 'session-42',          // deterministic when set
-    viewport: { width: 1920, height: 1080 },
+    viewport: { width: 1920, height: 1080 }, // ephemeral/persistent only — CDP uses the real window
     headless: false,             // defaults false so you can watch the recording
     cursor: true,                // auto-install visible cursor overlay (default true)
+    userDataDir: './.profile',   // persistent profile — stay logged in across runs
+    cdpUrl: 'http://localhost:9222', // OR attach to a browser you launched (precedence)
+    channel: 'chrome',           // launch installed Chrome instead of bundled Chromium
     launch: { args: ['--no-sandbox'] },  // forwarded to chromium.launch()
     context: { locale: 'en-US' },         // forwarded to browser.newContext()
   },
@@ -93,6 +105,31 @@ await record(
 **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.
+## Recording a logged-in flow
+By default each `record()` call uses a fresh, signed-out browser. Two ways to record something behind a login:
+```ts
+// Persistent profile — sign in once (in a headed run), reuse it forever
+await record({ output: 'dashboard.mp4', userDataDir: './.humanjs-profile' }, async (human) => {
+  await human.goto('https://app.example.com/dashboard');
+});
+// Or attach to a browser you already launched (real logins/tabs)
+//   chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.humanjs-chrome"
+await record({ output: 'flow.mp4', cdpUrl: 'http://localhost:9222' }, async (human) => {
+  await human.goto('https://app.example.com/dashboard');
+});
+```
+- **`userDataDir`** keeps cookies/logins across runs (a dedicated profile, starts empty).
+- **`cdpUrl`** records a browser you launched yourself — its existing session. HumanJS **never closes** a browser it attached to; it only borrows it. Takes precedence over `userDataDir`.
+- **`channel`** (`'chrome'` / `'msedge'`) swaps the binary but, on its own, still uses a fresh profile — pair it with `userDataDir` or `cdpUrl` for real logins.
+> You can't attach to your everyday Chrome — it only exposes a CDP port when launched with `--remote-debugging-port`, and Chrome refuses that on the default profile. Use a dedicated `--user-data-dir` (you sign in once there), or `userDataDir` to let HumanJS manage one.
+> **Recording resolution in CDP mode:** the attached browser's real window size wins — `viewport` is intentionally not applied. HumanJS is borrowing a window it doesn't own, and forcing a size would only *emulate* one (letterboxing the capture so the frames don't match what you see). Need a specific resolution? Launch the browser with `--window-size=1920,1080` to size the real window, or use the default/persistent modes where HumanJS owns the window and `viewport` applies directly.
 ## Quality presets
 Pick the preset that matches the recording's purpose:

package/dist/index.cjs CHANGED Viewed

@@ -24,50 +24,91 @@ async function record(optionsOrFn, maybeFn) {
     viewport,
     headless,
     launch,
-    context,
+    context: contextOptions,
+    userDataDir,
+    cdpUrl,
+    channel,
     cursor,
     ...createHumanOptions
   } = options;
   const resolvedQuality = quality ?? "high";
   const browserPreset = QUALITY_BROWSER_PRESETS[resolvedQuality];
-  const resolvedViewport = viewport ?? context?.viewport ?? browserPreset.viewport;
+  const resolvedViewport = viewport ?? contextOptions?.viewport ?? browserPreset.viewport;
   const wantsCapture = output !== void 0;
-  const browser = await playwright.chromium.launch({
-    ...launch,
-    headless: headless ?? false
+  const { page, dispose } = await acquireRecordingContext({
+    cdpUrl,
+    userDataDir,
+    channel,
+    headless: headless ?? false,
+    viewport: resolvedViewport,
+    launch,
+    context: contextOptions,
+    cursor
   });
   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);
+    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 });
       }
-      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);
     }
+    return recording;
   } finally {
-    await browser.close();
+    await dispose();
+  }
+}
+async function acquireRecordingContext(opts) {
+  const cursorOptions = typeof opts.cursor === "object" ? opts.cursor : void 0;
+  const installCursor = async (ctx) => {
+    if (opts.cursor !== false) await playwright.installMouseHelper(ctx, cursorOptions);
+  };
+  if (opts.cdpUrl) {
+    const browser2 = await playwright.chromium.connectOverCDP(opts.cdpUrl);
+    const context2 = browser2.contexts()[0] ?? await browser2.newContext({ ...opts.context });
+    await installCursor(context2);
+    const page2 = context2.pages()[0] ?? await context2.newPage();
+    return { page: page2, dispose: async () => void 0 };
   }
+  if (opts.userDataDir) {
+    const context2 = await playwright.chromium.launchPersistentContext(opts.userDataDir, {
+      ...opts.launch,
+      ...opts.context,
+      channel: opts.channel ?? opts.launch?.channel,
+      headless: opts.headless,
+      viewport: opts.viewport
+    });
+    await installCursor(context2);
+    const page2 = context2.pages()[0] ?? await context2.newPage();
+    return {
+      page: page2,
+      dispose: async () => {
+        await context2.close().catch(() => void 0);
+      }
+    };
+  }
+  const browser = await playwright.chromium.launch({
+    ...opts.launch,
+    channel: opts.channel ?? opts.launch?.channel,
+    headless: opts.headless
+  });
+  const context = await browser.newContext({ ...opts.context, viewport: opts.viewport });
+  await installCursor(context);
+  const page = await context.newPage();
+  return {
+    page,
+    dispose: async () => {
+      await context.close().catch(() => void 0);
+      await browser.close().catch(() => void 0);
+    }
+  };
 }
 exports.record = record;

package/dist/index.cjs.map CHANGED Viewed

	@@ -1 +1 @@
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"]}
1	+ {"version":3,"sources":["../src/record/index.ts"],"names":["createHuman","extname","installMouseHelper","browser","chromium","context","page"],"mappings":"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","file":"index.cjs","sourcesContent":["import { extname } from 'node:path';\nimport {\n type BrowserContext,\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 /\n Viewport dimensions. Overrides the quality preset's viewport. Applies to\n * the default and persistent (`userDataDir`) modes; ignored when attaching\n * over `cdpUrl`, where the real browser window's size wins (see `cdpUrl`).\n /\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 Record in a persistent profile at this directory so logins and\n * cookies survive across runs — sign in once (in a headed run), and later\n * recordings start authenticated. Uses `launchPersistentContext` under the\n * hood (a single context); `headless`, `launch`, `channel`, and `viewport`\n * still apply. Starts empty the first time.\n /\n readonly userDataDir?: string;\n /\n Record by attaching to a browser you already launched over CDP (e.g.\n * `\"http://localhost:9222\"`). Reuses that browser's existing context — your\n * real logins, tabs, extensions. Start the browser yourself with\n * `--remote-debugging-port`. HumanJS never closes a browser it attached to;\n * it only borrows it. Takes precedence over `userDataDir`.\n \n `launch` / `headless` / `channel` / `viewport` don't apply here — you're\n * borrowing a window HumanJS doesn't own, so the browser's real window size\n * wins. Forcing a `viewport` would only emulate one and letterbox the\n * capture. For a fixed recording resolution, launch the browser yourself\n * with `--window-size=1920,1080`, or use the default / persistent modes.\n /\n readonly cdpUrl?: string;\n /\n Playwright browser channel — e.g. `'chrome'`, `'msedge'`. Launches that\n * installed browser's binary instead of bundled Chromium (applies to the\n * default and `userDataDir` modes). NOTE: a channel alone does NOT reuse\n * your existing profile — pair it with `userDataDir` (persistent) or\n * `cdpUrl` (attach) for real logins.\n /\n readonly channel?: string;\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 (or attaches to) a browser, opens a\n * page, creates a humanized session, runs `fn`, and returns a\n * {@link Recording} you can export to video, JSON timeline, or read in-memory.\n \n Browser source (default → ephemeral fresh profile):\n * - `userDataDir` — a persistent profile that keeps logins across runs.\n * - `cdpUrl` — attach to a browser you launched yourself (real logins/tabs);\n * never closed on finish, only released.\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 * // Stay signed in across runs (persistent profile)\n * await record({ output: 'dashboard.mp4', userDataDir: './.humanjs-profile' }, async (human) => {\n * await human.goto('https://app.example.com/dashboard');\n * });\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: contextOptions,\n userDataDir,\n cdpUrl,\n channel,\n cursor,\n ...createHumanOptions\n } = options;\n\n const resolvedQuality: RecordingQuality = quality ?? 'high';\n const browserPreset = QUALITY_BROWSER_PRESETS[resolvedQuality];\n const resolvedViewport = viewport ?? contextOptions?.viewport ?? browserPreset.viewport;\n const wantsCapture = output !== undefined;\n\n const { page, dispose } = await acquireRecordingContext({\n cdpUrl,\n userDataDir,\n channel,\n headless: headless ?? false,\n viewport: resolvedViewport,\n launch,\n context: contextOptions,\n cursor,\n });\n\n try {\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 dispose();\n }\n}\n\n/* Internal options for {@link acquireRecordingContext}. /\ninterface AcquireOptions {\n readonly cdpUrl?: string;\n readonly userDataDir?: string;\n readonly channel?: string;\n readonly headless: boolean;\n readonly viewport: { readonly width: number; readonly height: number };\n readonly launch?: LaunchOptions;\n readonly context?: BrowserContextOptions;\n readonly cursor?: boolean \| InstallMouseHelperOptions;\n}\n\n/\n Resolves the browser source — CDP attach > persistent profile > ephemeral\n * — and returns the page to drive plus a `dispose` that tears down only what\n * we created. A CDP-attached browser is borrowed: `dispose` leaves it (and\n * its context) untouched so we never close the caller's real browser.\n */\nasync function acquireRecordingContext(\n opts: AcquireOptions,\n): Promise<{ page: Page; dispose: () => Promise<void> }> {\n const cursorOptions = typeof opts.cursor === 'object' ? opts.cursor : undefined;\n const installCursor = async (ctx: BrowserContext): Promise<void> => {\n if (opts.cursor !== false) await installMouseHelper(ctx, cursorOptions);\n };\n\n // Attach to a browser the caller launched. Reuse its existing context so we\n // record their real session; only make a fresh one if there's none. Never\n // close it on dispose — it's borrowed.\n if (opts.cdpUrl) {\n const browser = await chromium.connectOverCDP(opts.cdpUrl);\n const context = browser.contexts()[0] ?? (await browser.newContext({ ...opts.context }));\n await installCursor(context);\n const page = context.pages()[0] ?? (await context.newPage());\n return { page, dispose: async () => undefined };\n }\n\n // Persistent profile — the context owns its browser, so closing it on\n // dispose tears everything down.\n if (opts.userDataDir) {\n const context = await chromium.launchPersistentContext(opts.userDataDir, {\n ...opts.launch,\n ...opts.context,\n channel: opts.channel ?? opts.launch?.channel,\n headless: opts.headless,\n viewport: opts.viewport,\n });\n await installCursor(context);\n const page = context.pages()[0] ?? (await context.newPage());\n return {\n page,\n dispose: async () => {\n await context.close().catch(() => undefined);\n },\n };\n }\n\n // Ephemeral (default) — a fresh throwaway browser + context.\n const browser = await chromium.launch({\n ...opts.launch,\n channel: opts.channel ?? opts.launch?.channel,\n headless: opts.headless,\n });\n const context = await browser.newContext({ ...opts.context, viewport: opts.viewport });\n await installCursor(context);\n const page = await context.newPage();\n return {\n page,\n dispose: async () => {\n await context.close().catch(() => undefined);\n await browser.close().catch(() => undefined);\n },\n };\n}\n"]}

package/dist/index.d.cts CHANGED Viewed

@@ -26,7 +26,11 @@ interface RecordOptions extends CreateHumanOptions {
     readonly quality?: RecordingQuality;
     /** Optional URL to navigate to before the callback runs. */
     readonly url?: string;
-    /** Viewport dimensions. Overrides the quality preset's viewport. */
+    /**
+     * Viewport dimensions. Overrides the quality preset's viewport. Applies to
+     * the default and persistent (`userDataDir`) modes; ignored when attaching
+     * over `cdpUrl`, where the real browser window's size wins (see `cdpUrl`).
+     */
     readonly viewport?: {
         readonly width: number;
         readonly height: number;
@@ -37,6 +41,36 @@ interface RecordOptions extends CreateHumanOptions {
     readonly launch?: LaunchOptions;
     /** Forwarded to `browser.newContext()` (alongside `viewport`). */
     readonly context?: BrowserContextOptions;
+    /**
+     * Record in a **persistent profile** at this directory so logins and
+     * cookies survive across runs — sign in once (in a headed run), and later
+     * recordings start authenticated. Uses `launchPersistentContext` under the
+     * hood (a single context); `headless`, `launch`, `channel`, and `viewport`
+     * still apply. Starts empty the first time.
+     */
+    readonly userDataDir?: string;
+    /**
+     * Record by **attaching to a browser you already launched** over CDP (e.g.
+     * `"http://localhost:9222"`). Reuses that browser's existing context — your
+     * real logins, tabs, extensions. Start the browser yourself with
+     * `--remote-debugging-port`. HumanJS never closes a browser it attached to;
+     * it only borrows it. Takes precedence over `userDataDir`.
+     *
+     * `launch` / `headless` / `channel` / `viewport` don't apply here — you're
+     * borrowing a window HumanJS doesn't own, so the browser's real window size
+     * wins. Forcing a `viewport` would only *emulate* one and letterbox the
+     * capture. For a fixed recording resolution, launch the browser yourself
+     * with `--window-size=1920,1080`, or use the default / persistent modes.
+     */
+    readonly cdpUrl?: string;
+    /**
+     * Playwright browser channel — e.g. `'chrome'`, `'msedge'`. Launches that
+     * installed browser's binary instead of bundled Chromium (applies to the
+     * default and `userDataDir` modes). NOTE: a channel alone does NOT reuse
+     * your existing profile — pair it with `userDataDir` (persistent) or
+     * `cdpUrl` (attach) for real logins.
+     */
+    readonly channel?: string;
     /**
      * Install the HumanJS visible cursor overlay so recorded videos show
      * mouse motion — Playwright's synthetic mouse doesn't render a cursor
@@ -58,9 +92,14 @@ interface RecordOptions extends CreateHumanOptions {
 /** 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.
+ * One-call session recording. Launches (or attaches to) 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.
+ *
+ * Browser source (default → ephemeral fresh profile):
+ * - `userDataDir` — a persistent profile that keeps logins across runs.
+ * - `cdpUrl` — attach to a browser you launched yourself (real logins/tabs);
+ *   never closed on finish, only released.
  *
  * If `options.output` is set, the output file is written to that path before
  * `record()` resolves — extension dispatches to `toVideo` (`.mp4` / `.webm`)
@@ -81,11 +120,10 @@ type RecordCallback = (human: Human, page: Page) => Promise<void>;
  *
  * @example
  * ```ts
- * // Timeline only, no video overhead
- * const rec = await record(async (human) => {
- *   await human.click('#login');
+ * // Stay signed in across runs (persistent profile)
+ * await record({ output: 'dashboard.mp4', userDataDir: './.humanjs-profile' }, async (human) => {
+ *   await human.goto('https://app.example.com/dashboard');
  * });
- * await rec.toTimeline('demo.json');
  * ```
  *
  * For multi-page flows or recording a slice of a larger session, use

package/dist/index.d.ts CHANGED Viewed

@@ -26,7 +26,11 @@ interface RecordOptions extends CreateHumanOptions {
     readonly quality?: RecordingQuality;
     /** Optional URL to navigate to before the callback runs. */
     readonly url?: string;
-    /** Viewport dimensions. Overrides the quality preset's viewport. */
+    /**
+     * Viewport dimensions. Overrides the quality preset's viewport. Applies to
+     * the default and persistent (`userDataDir`) modes; ignored when attaching
+     * over `cdpUrl`, where the real browser window's size wins (see `cdpUrl`).
+     */
     readonly viewport?: {
         readonly width: number;
         readonly height: number;
@@ -37,6 +41,36 @@ interface RecordOptions extends CreateHumanOptions {
     readonly launch?: LaunchOptions;
     /** Forwarded to `browser.newContext()` (alongside `viewport`). */
     readonly context?: BrowserContextOptions;
+    /**
+     * Record in a **persistent profile** at this directory so logins and
+     * cookies survive across runs — sign in once (in a headed run), and later
+     * recordings start authenticated. Uses `launchPersistentContext` under the
+     * hood (a single context); `headless`, `launch`, `channel`, and `viewport`
+     * still apply. Starts empty the first time.
+     */
+    readonly userDataDir?: string;
+    /**
+     * Record by **attaching to a browser you already launched** over CDP (e.g.
+     * `"http://localhost:9222"`). Reuses that browser's existing context — your
+     * real logins, tabs, extensions. Start the browser yourself with
+     * `--remote-debugging-port`. HumanJS never closes a browser it attached to;
+     * it only borrows it. Takes precedence over `userDataDir`.
+     *
+     * `launch` / `headless` / `channel` / `viewport` don't apply here — you're
+     * borrowing a window HumanJS doesn't own, so the browser's real window size
+     * wins. Forcing a `viewport` would only *emulate* one and letterbox the
+     * capture. For a fixed recording resolution, launch the browser yourself
+     * with `--window-size=1920,1080`, or use the default / persistent modes.
+     */
+    readonly cdpUrl?: string;
+    /**
+     * Playwright browser channel — e.g. `'chrome'`, `'msedge'`. Launches that
+     * installed browser's binary instead of bundled Chromium (applies to the
+     * default and `userDataDir` modes). NOTE: a channel alone does NOT reuse
+     * your existing profile — pair it with `userDataDir` (persistent) or
+     * `cdpUrl` (attach) for real logins.
+     */
+    readonly channel?: string;
     /**
      * Install the HumanJS visible cursor overlay so recorded videos show
      * mouse motion — Playwright's synthetic mouse doesn't render a cursor
@@ -58,9 +92,14 @@ interface RecordOptions extends CreateHumanOptions {
 /** 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.
+ * One-call session recording. Launches (or attaches to) 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.
+ *
+ * Browser source (default → ephemeral fresh profile):
+ * - `userDataDir` — a persistent profile that keeps logins across runs.
+ * - `cdpUrl` — attach to a browser you launched yourself (real logins/tabs);
+ *   never closed on finish, only released.
  *
  * If `options.output` is set, the output file is written to that path before
  * `record()` resolves — extension dispatches to `toVideo` (`.mp4` / `.webm`)
@@ -81,11 +120,10 @@ type RecordCallback = (human: Human, page: Page) => Promise<void>;
  *
  * @example
  * ```ts
- * // Timeline only, no video overhead
- * const rec = await record(async (human) => {
- *   await human.click('#login');
+ * // Stay signed in across runs (persistent profile)
+ * await record({ output: 'dashboard.mp4', userDataDir: './.humanjs-profile' }, async (human) => {
+ *   await human.goto('https://app.example.com/dashboard');
  * });
- * await rec.toTimeline('demo.json');
  * ```
  *
  * For multi-page flows or recording a slice of a larger session, use

package/dist/index.js CHANGED Viewed

@@ -1,5 +1,5 @@
 import { extname } from 'path';
-import { chromium, installMouseHelper, createHuman } from '@humanjs/playwright';
+import { createHuman, chromium, installMouseHelper } from '@humanjs/playwright';
 // src/record/index.ts
 var QUALITY_BROWSER_PRESETS = {
@@ -22,50 +22,91 @@ async function record(optionsOrFn, maybeFn) {
     viewport,
     headless,
     launch,
-    context,
+    context: contextOptions,
+    userDataDir,
+    cdpUrl,
+    channel,
     cursor,
     ...createHumanOptions
   } = options;
   const resolvedQuality = quality ?? "high";
   const browserPreset = QUALITY_BROWSER_PRESETS[resolvedQuality];
-  const resolvedViewport = viewport ?? context?.viewport ?? browserPreset.viewport;
+  const resolvedViewport = viewport ?? contextOptions?.viewport ?? browserPreset.viewport;
   const wantsCapture = output !== void 0;
-  const browser = await chromium.launch({
-    ...launch,
-    headless: headless ?? false
+  const { page, dispose } = await acquireRecordingContext({
+    cdpUrl,
+    userDataDir,
+    channel,
+    headless: headless ?? false,
+    viewport: resolvedViewport,
+    launch,
+    context: contextOptions,
+    cursor
   });
   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);
+    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 });
       }
-      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);
     }
+    return recording;
   } finally {
-    await browser.close();
+    await dispose();
+  }
+}
+async function acquireRecordingContext(opts) {
+  const cursorOptions = typeof opts.cursor === "object" ? opts.cursor : void 0;
+  const installCursor = async (ctx) => {
+    if (opts.cursor !== false) await installMouseHelper(ctx, cursorOptions);
+  };
+  if (opts.cdpUrl) {
+    const browser2 = await chromium.connectOverCDP(opts.cdpUrl);
+    const context2 = browser2.contexts()[0] ?? await browser2.newContext({ ...opts.context });
+    await installCursor(context2);
+    const page2 = context2.pages()[0] ?? await context2.newPage();
+    return { page: page2, dispose: async () => void 0 };
   }
+  if (opts.userDataDir) {
+    const context2 = await chromium.launchPersistentContext(opts.userDataDir, {
+      ...opts.launch,
+      ...opts.context,
+      channel: opts.channel ?? opts.launch?.channel,
+      headless: opts.headless,
+      viewport: opts.viewport
+    });
+    await installCursor(context2);
+    const page2 = context2.pages()[0] ?? await context2.newPage();
+    return {
+      page: page2,
+      dispose: async () => {
+        await context2.close().catch(() => void 0);
+      }
+    };
+  }
+  const browser = await chromium.launch({
+    ...opts.launch,
+    channel: opts.channel ?? opts.launch?.channel,
+    headless: opts.headless
+  });
+  const context = await browser.newContext({ ...opts.context, viewport: opts.viewport });
+  await installCursor(context);
+  const page = await context.newPage();
+  return {
+    page,
+    dispose: async () => {
+      await context.close().catch(() => void 0);
+      await browser.close().catch(() => void 0);
+    }
+  };
 }
 export { record };

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
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"]}
1	+ {"version":3,"sources":["../src/record/index.ts"],"names":["browser","context","page"],"mappings":"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","file":"index.js","sourcesContent":["import { extname } from 'node:path';\nimport {\n type BrowserContext,\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 /\n Viewport dimensions. Overrides the quality preset's viewport. Applies to\n * the default and persistent (`userDataDir`) modes; ignored when attaching\n * over `cdpUrl`, where the real browser window's size wins (see `cdpUrl`).\n /\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 Record in a persistent profile at this directory so logins and\n * cookies survive across runs — sign in once (in a headed run), and later\n * recordings start authenticated. Uses `launchPersistentContext` under the\n * hood (a single context); `headless`, `launch`, `channel`, and `viewport`\n * still apply. Starts empty the first time.\n /\n readonly userDataDir?: string;\n /\n Record by attaching to a browser you already launched over CDP (e.g.\n * `\"http://localhost:9222\"`). Reuses that browser's existing context — your\n * real logins, tabs, extensions. Start the browser yourself with\n * `--remote-debugging-port`. HumanJS never closes a browser it attached to;\n * it only borrows it. Takes precedence over `userDataDir`.\n \n `launch` / `headless` / `channel` / `viewport` don't apply here — you're\n * borrowing a window HumanJS doesn't own, so the browser's real window size\n * wins. Forcing a `viewport` would only emulate one and letterbox the\n * capture. For a fixed recording resolution, launch the browser yourself\n * with `--window-size=1920,1080`, or use the default / persistent modes.\n /\n readonly cdpUrl?: string;\n /\n Playwright browser channel — e.g. `'chrome'`, `'msedge'`. Launches that\n * installed browser's binary instead of bundled Chromium (applies to the\n * default and `userDataDir` modes). NOTE: a channel alone does NOT reuse\n * your existing profile — pair it with `userDataDir` (persistent) or\n * `cdpUrl` (attach) for real logins.\n /\n readonly channel?: string;\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 (or attaches to) a browser, opens a\n * page, creates a humanized session, runs `fn`, and returns a\n * {@link Recording} you can export to video, JSON timeline, or read in-memory.\n \n Browser source (default → ephemeral fresh profile):\n * - `userDataDir` — a persistent profile that keeps logins across runs.\n * - `cdpUrl` — attach to a browser you launched yourself (real logins/tabs);\n * never closed on finish, only released.\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 * // Stay signed in across runs (persistent profile)\n * await record({ output: 'dashboard.mp4', userDataDir: './.humanjs-profile' }, async (human) => {\n * await human.goto('https://app.example.com/dashboard');\n * });\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: contextOptions,\n userDataDir,\n cdpUrl,\n channel,\n cursor,\n ...createHumanOptions\n } = options;\n\n const resolvedQuality: RecordingQuality = quality ?? 'high';\n const browserPreset = QUALITY_BROWSER_PRESETS[resolvedQuality];\n const resolvedViewport = viewport ?? contextOptions?.viewport ?? browserPreset.viewport;\n const wantsCapture = output !== undefined;\n\n const { page, dispose } = await acquireRecordingContext({\n cdpUrl,\n userDataDir,\n channel,\n headless: headless ?? false,\n viewport: resolvedViewport,\n launch,\n context: contextOptions,\n cursor,\n });\n\n try {\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 dispose();\n }\n}\n\n/* Internal options for {@link acquireRecordingContext}. /\ninterface AcquireOptions {\n readonly cdpUrl?: string;\n readonly userDataDir?: string;\n readonly channel?: string;\n readonly headless: boolean;\n readonly viewport: { readonly width: number; readonly height: number };\n readonly launch?: LaunchOptions;\n readonly context?: BrowserContextOptions;\n readonly cursor?: boolean \| InstallMouseHelperOptions;\n}\n\n/\n Resolves the browser source — CDP attach > persistent profile > ephemeral\n * — and returns the page to drive plus a `dispose` that tears down only what\n * we created. A CDP-attached browser is borrowed: `dispose` leaves it (and\n * its context) untouched so we never close the caller's real browser.\n */\nasync function acquireRecordingContext(\n opts: AcquireOptions,\n): Promise<{ page: Page; dispose: () => Promise<void> }> {\n const cursorOptions = typeof opts.cursor === 'object' ? opts.cursor : undefined;\n const installCursor = async (ctx: BrowserContext): Promise<void> => {\n if (opts.cursor !== false) await installMouseHelper(ctx, cursorOptions);\n };\n\n // Attach to a browser the caller launched. Reuse its existing context so we\n // record their real session; only make a fresh one if there's none. Never\n // close it on dispose — it's borrowed.\n if (opts.cdpUrl) {\n const browser = await chromium.connectOverCDP(opts.cdpUrl);\n const context = browser.contexts()[0] ?? (await browser.newContext({ ...opts.context }));\n await installCursor(context);\n const page = context.pages()[0] ?? (await context.newPage());\n return { page, dispose: async () => undefined };\n }\n\n // Persistent profile — the context owns its browser, so closing it on\n // dispose tears everything down.\n if (opts.userDataDir) {\n const context = await chromium.launchPersistentContext(opts.userDataDir, {\n ...opts.launch,\n ...opts.context,\n channel: opts.channel ?? opts.launch?.channel,\n headless: opts.headless,\n viewport: opts.viewport,\n });\n await installCursor(context);\n const page = context.pages()[0] ?? (await context.newPage());\n return {\n page,\n dispose: async () => {\n await context.close().catch(() => undefined);\n },\n };\n }\n\n // Ephemeral (default) — a fresh throwaway browser + context.\n const browser = await chromium.launch({\n ...opts.launch,\n channel: opts.channel ?? opts.launch?.channel,\n headless: opts.headless,\n });\n const context = await browser.newContext({ ...opts.context, viewport: opts.viewport });\n await installCursor(context);\n const page = await context.newPage();\n return {\n page,\n dispose: async () => {\n await context.close().catch(() => undefined);\n await browser.close().catch(() => undefined);\n },\n };\n}\n"]}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@humanjs/recorder",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "One-call session recording for HumanJS — capture a humanized Playwright session as mp4, webm, gif, or a structured JSON timeline.",
   "keywords": [
     "humanjs",
@@ -49,7 +49,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@humanjs/playwright": "0.5.0"
+    "@humanjs/playwright": "0.6.0"
   },
   "peerDependencies": {
     "playwright": ">=1.40.0"