@rezkam/browser-tools 2.0.0 → 2.1.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # @rezkam/browser-tools
2
2
 
3
+ ## 2.1.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 924caa5: Add `--viewport <width>x<height> [--mobile] [--scale <n>]` to `screenshot`, `eval`, and `nav`, and `screenshot --selector <css>` for one element. A screen size sent with `cdp call` ended with that call, so later commands silently saw a desktop page; the size is now held for the command that asks for it, without reloading the tab, and `cdp call` says when an Emulation override will not last. `screenshot` reports the image size and fails when a viewport capture does not match the requested size, and element captures no longer wait forever on background tabs. Library code can use `capturePage` and `withViewport` from `@rezkam/browser-tools/viewport.mjs`.
8
+
3
9
  ## 2.0.0
4
10
 
5
11
  ### Major Changes
package/README.md CHANGED
@@ -74,7 +74,7 @@ Use `--profile "<profile or alias>"` when an existing login is needed, `--sync`
74
74
  | Browser lifecycle | `start`, `status`, `stop` | Launch, inspect, stop, clean, reap, and prune managed Chrome sessions |
75
75
  | Extensions | `extensions load`, `extensions update` | Load trusted unpacked extensions or reload updated files while retaining identity and settings |
76
76
  | Profile configuration | `config` | Discover profiles, list active profiles, and manage task-to-profile mappings |
77
- | Page control | `nav`, `eval`, `screenshot` | Navigate the active tab or a new background tab, run page JavaScript, and capture PNG screenshots |
77
+ | Page control | `nav`, `eval`, `screenshot` | Navigate the active tab or a new background tab, run page JavaScript, and capture PNG screenshots of the viewport, the full page, or one element, optionally at a set screen size |
78
78
  | DOM inspection | `pick` | Select one or more visible elements and return tag, id, class, text, HTML, and parent information |
79
79
  | Page extraction | `scrape-page`, `extract-article` | Extract article-like links with timestamps or readable article text from the active tab |
80
80
  | Visual recording | `record-gif`, `review-gif` | Record an interaction with pre-roll and post-roll frames, then create a contact sheet and metadata report |
@@ -135,6 +135,24 @@ The root package export and `@rezkam/browser-tools/browser-control.mjs` both exp
135
135
 
136
136
  The Rebrowser backend does not send `Runtime.enable`, because pages can detect it. As a result `page.on('console')` and `page.on('pageerror')` receive nothing, without an error. Page evaluation, navigation, network events, and `exposeFunction` are unaffected. Browser Tools keeps that protection on and offers no way to turn it off. Read page state with `page.evaluate` instead, or have the page report through `exposeFunction`.
137
137
 
138
+ ### Screen size and screenshots
139
+
140
+ ```bash
141
+ browser-tools screenshot --viewport 375x667 --mobile --port <reported port>
142
+ browser-tools eval --viewport 375x667 --mobile 'innerWidth' --port <reported port>
143
+ ```
144
+
145
+ `--viewport <width>x<height> [--mobile] [--scale <n>]` works on `screenshot`, `eval`, and `nav`, and `screenshot --selector <css>` captures one element. The size lasts for that one command, because Chrome drops an emulated size when the CDP session that set it ends. For the same reason a size sent with `browser-tools cdp call Emulation.setDeviceMetricsOverride` is gone before the next command runs. `screenshot` reports the image size on stderr and fails when a viewport capture does not match the requested size.
146
+
147
+ ```js
148
+ import { capturePage, withViewport } from '@rezkam/browser-tools/viewport.mjs';
149
+
150
+ const viewport = { width: 375, height: 667, deviceScaleFactor: 2, mobile: true };
151
+ const png = await capturePage(page, { viewport, selector: 'table.results' });
152
+ ```
153
+
154
+ Use `capturePage` on managed tabs in place of Puppeteer's `elementHandle.screenshot()`, which never finishes on a background tab, and `page.screenshot()`, which ignores the scale of a size set on another session.
155
+
138
156
  ### Shared tabs
139
157
 
140
158
  `browser-tools serve` starts a tab broker and prints `{"url": ...}` once it listens. Chrome starts with the first lease, without extensions, component apps, a startup window or background networking.
@@ -10,9 +10,9 @@
10
10
  * browser-tools start [--task <task>] [--profile <name>] [--headless] [--sync] [--port <n>]
11
11
  * browser-tools status [--port <n>] [--json]
12
12
  * browser-tools stop [--clean] [--dry-run] [--prune]
13
- * browser-tools nav <url> [--new] [--port <n>]
14
- * browser-tools eval '<javascript>' [--port <n>]
15
- * browser-tools screenshot [--full] [--port <n>]
13
+ * browser-tools nav <url> [--new] [--viewport <w>x<h> [--mobile] [--scale <n>]] [--port <n>]
14
+ * browser-tools eval '<javascript>' [--viewport <w>x<h> [--mobile] [--scale <n>]] [--port <n>]
15
+ * browser-tools screenshot [--full | --selector <css>] [--viewport <w>x<h> [--mobile] [--scale <n>]] [--port <n>]
16
16
  * browser-tools record-gif start|status|stop [options]
17
17
  * browser-tools review-gif <meaningful.gif> [options]
18
18
  * browser-tools record-har start|status|stop [options]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rezkam/browser-tools",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "description": "Sandboxed, owner-token-protected Chrome automation for AI agents: control pages, record and review GIFs, capture HAR and raw CDP events, send CDP calls, and manage Chrome profiles.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -24,6 +24,7 @@
24
24
  "./resource-helper.mjs": "./scripts/resource-helper.mjs",
25
25
  "./extensions.mjs": "./scripts/extensions.mjs",
26
26
  "./tab-broker.mjs": "./scripts/tab-broker.mjs",
27
+ "./viewport.mjs": "./scripts/viewport.mjs",
27
28
  "./package.json": "./package.json"
28
29
  },
29
30
  "files": [
package/scripts/cdp.mjs CHANGED
@@ -22,6 +22,7 @@ import {
22
22
  validateCdpMethod,
23
23
  withPageCdpSession,
24
24
  } from './cdp-common.mjs';
25
+ import { SESSION_SCOPED_NOTE } from './viewport.mjs';
25
26
 
26
27
  const SCRIPT_FILE = fileURLToPath(import.meta.url);
27
28
 
@@ -36,7 +37,9 @@ Options:
36
37
  --owner-token <token> Prefer ${OWNER_TOKEN_ENV} instead
37
38
 
38
39
  Direct calls target the active tab and require its owner token. Methods that bypass
39
- managed-browser lifecycle safety are blocked. Prefer --params-file for sensitive input.`);
40
+ managed-browser lifecycle safety are blocked. Prefer --params-file for sensitive input.
41
+ Each call uses its own CDP session, so Emulation overrides end when the call returns.
42
+ For a screen size, use --viewport on screenshot, eval, or nav.`);
40
43
  }
41
44
 
42
45
  function parseParams(args) {
@@ -80,6 +83,7 @@ async function callMethod(args) {
80
83
  const result = await withPageCdpSession(port, ownerToken, ({ session }) => session.send(method, params));
81
84
  const output = sanitizeCdpCallResult(method, result, { redact: hasFlag(rest, '--redact') });
82
85
  console.log(JSON.stringify(output, null, 2));
86
+ if (/^Emulation\.set/.test(method)) console.error(SESSION_SCOPED_NOTE);
83
87
  }
84
88
 
85
89
  export async function main(args = process.argv.slice(2)) {
package/scripts/eval.mjs CHANGED
@@ -7,6 +7,7 @@
7
7
  * scripts/eval.mjs 'document.title'
8
8
  * scripts/eval.mjs 'await fetch("/api/data").then(r => r.json())'
9
9
  * scripts/eval.mjs --port 9223 'document.title'
10
+ * scripts/eval.mjs --viewport 375x667 --mobile 'innerWidth'
10
11
  * scripts/eval.mjs --owner-token "$BROWSER_TOOLS_OWNER_TOKEN" 'document.title'
11
12
  */
12
13
 
@@ -14,6 +15,7 @@ import { realpathSync } from 'node:fs';
14
15
  import { fileURLToPath } from 'node:url';
15
16
  import { format } from 'node:util';
16
17
  import { activePage, parseOwnerToken, parsePort, stripBrowserSessionArgs, withBrowser } from './browser-control.mjs';
18
+ import { parseViewport, stripViewportArgs, withViewport } from './viewport.mjs';
17
19
 
18
20
  if (isDirectExecution()) await main();
19
21
 
@@ -21,10 +23,17 @@ async function main() {
21
23
  const args = process.argv.slice(2);
22
24
  const port = parsePort(args);
23
25
  const ownerToken = parseOwnerToken(args);
24
- const code = stripBrowserSessionArgs(args).join(' ');
26
+ let viewport;
27
+ try {
28
+ viewport = parseViewport(args);
29
+ } catch (error) {
30
+ console.error(`✗ ${error.message}`);
31
+ process.exit(1);
32
+ }
33
+ const code = stripViewportArgs(stripBrowserSessionArgs(args)).join(' ');
25
34
 
26
35
  if (!code) {
27
- console.log("Usage: eval.js [--port <n>] '<javascript>'");
36
+ console.log("Usage: eval.js [--port <n>] [--viewport <width>x<height> [--mobile] [--scale <n>]] '<javascript>'");
28
37
  console.log(" ./eval.js 'document.title'");
29
38
  console.log(' ./eval.js \'document.querySelectorAll("a").length\'');
30
39
  process.exit(1);
@@ -32,10 +41,10 @@ async function main() {
32
41
 
33
42
  await withBrowser(port, async (browser) => {
34
43
  const page = await activePage(browser);
35
- const result = await page.evaluate((c) => {
44
+ const result = await withViewport(page, viewport, () => page.evaluate((c) => {
36
45
  const AsyncFunction = (async () => {}).constructor;
37
46
  return new AsyncFunction(`return (${c})`)();
38
- }, code);
47
+ }, code));
39
48
 
40
49
  printResult(result);
41
50
  }, { ownerToken });
package/scripts/nav.mjs CHANGED
@@ -6,19 +6,28 @@
6
6
  * scripts/nav.mjs https://example.com
7
7
  * scripts/nav.mjs https://example.com --new
8
8
  * scripts/nav.mjs https://example.com --port 9223
9
+ * scripts/nav.mjs https://example.com --viewport 375x667 --mobile
9
10
  * scripts/nav.mjs https://example.com --owner-token "$BROWSER_TOOLS_OWNER_TOKEN"
10
11
  */
11
12
 
12
13
  import { activePage, hasFlag, parseOwnerToken, parsePort, withBrowser } from './browser-control.mjs';
14
+ import { parseViewport, withViewport } from './viewport.mjs';
13
15
 
14
16
  const args = process.argv.slice(2);
15
17
  const url = args.find((a) => a.startsWith('http') || a.startsWith('file'));
16
18
  const newTab = hasFlag(args, '--new');
17
19
  const port = parsePort(args);
18
20
  const ownerToken = parseOwnerToken(args);
21
+ let viewport;
22
+ try {
23
+ viewport = parseViewport(args);
24
+ } catch (error) {
25
+ console.error(`✗ ${error.message}`);
26
+ process.exit(1);
27
+ }
19
28
 
20
29
  if (!url) {
21
- console.log('Usage: scripts/nav.mjs <url> [--new] [--port <n>]');
30
+ console.log('Usage: scripts/nav.mjs <url> [--new] [--port <n>] [--viewport <width>x<height> [--mobile] [--scale <n>]]');
22
31
  console.log(' scripts/nav.mjs https://example.com');
23
32
  console.log(' scripts/nav.mjs https://example.com --new');
24
33
  process.exit(1);
@@ -27,12 +36,12 @@ if (!url) {
27
36
  await withBrowser(port, async (browser) => {
28
37
  if (newTab) {
29
38
  const page = await browser.newPage({ background: true });
30
- await page.goto(url, { waitUntil: 'domcontentloaded' });
39
+ await withViewport(page, viewport, () => page.goto(url, { waitUntil: 'domcontentloaded' }));
31
40
  console.log(`✓ Opened new tab: ${url}`);
32
41
  return;
33
42
  }
34
43
 
35
44
  const page = await activePage(browser);
36
- await page.goto(url, { waitUntil: 'domcontentloaded' });
45
+ await withViewport(page, viewport, () => page.goto(url, { waitUntil: 'domcontentloaded' }));
37
46
  console.log(`✓ Navigated to: ${url}`);
38
47
  }, { ownerToken });
@@ -1,25 +1,40 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * Take a screenshot of the active tab's viewport.
3
+ * Take a screenshot of the active tab's viewport, full page, or one element.
4
4
  * Prints the file path so the agent can read it.
5
5
  *
6
6
  * Usage:
7
7
  * scripts/screenshot.mjs
8
8
  * scripts/screenshot.mjs --port 9223
9
9
  * scripts/screenshot.mjs --full
10
+ * scripts/screenshot.mjs --viewport 375x667 --mobile
11
+ * scripts/screenshot.mjs --viewport 375x667 --scale 2 --selector 'table.results'
10
12
  * scripts/screenshot.mjs --owner-token "$BROWSER_TOOLS_OWNER_TOKEN"
11
13
  */
12
14
 
13
- import { activePage, hasFlag, parseOwnerToken, parsePort, timestampedTmpPath, withBrowser } from './browser-control.mjs';
15
+ import { writeFileSync } from 'node:fs';
16
+ import { activePage, hasFlag, parseOwnerToken, parsePort, requiredOptionValue, timestampedTmpPath, withBrowser } from './browser-control.mjs';
17
+ import { capturePage, parseViewport, pngSize } from './viewport.mjs';
14
18
 
15
- const args = process.argv.slice(2);
16
- const port = parsePort(args);
17
- const ownerToken = parseOwnerToken(args);
18
- const fullPage = hasFlag(args, '--full');
19
+ try {
20
+ const args = process.argv.slice(2);
21
+ const port = parsePort(args);
22
+ const ownerToken = parseOwnerToken(args);
23
+ const fullPage = hasFlag(args, '--full');
24
+ const selector = requiredOptionValue(args, '--selector', null);
25
+ const viewport = parseViewport(args);
26
+ if (fullPage && selector) throw new Error('Use only one of --full or --selector');
19
27
 
20
- await withBrowser(port, async (browser) => {
21
- const page = await activePage(browser);
22
- const filepath = timestampedTmpPath('browser-screenshot', 'png');
23
- await page.screenshot({ path: filepath, fullPage });
24
- console.log(filepath);
25
- }, { ownerToken });
28
+ await withBrowser(port, async (browser) => {
29
+ const page = await activePage(browser);
30
+ const filepath = timestampedTmpPath('browser-screenshot', 'png');
31
+ const image = await capturePage(page, { viewport, fullPage, selector });
32
+ writeFileSync(filepath, image);
33
+ const { width, height } = pngSize(image);
34
+ console.error(`${width}x${height} px`);
35
+ console.log(filepath);
36
+ }, { ownerToken });
37
+ } catch (error) {
38
+ console.error(`✗ ${error.message}`);
39
+ process.exitCode = 1;
40
+ }
@@ -0,0 +1,150 @@
1
+ /**
2
+ * Screen-size options shared by the commands that look at a page.
3
+ *
4
+ * Chrome keeps an emulated screen size only while the CDP session that set it stays attached, and
5
+ * every CLI command is its own session. So the size is applied inside the command that needs it,
6
+ * on a session held for exactly that long. Puppeteer's page.setViewport is avoided on purpose: it
7
+ * reloads the page whenever the mobile flag changes, which would throw away the state of the tab.
8
+ */
9
+
10
+ const VIEWPORT_OPTIONS_WITH_VALUES = new Set(['--viewport', '--scale']);
11
+ const VIEWPORT_FLAGS = new Set(['--mobile']);
12
+
13
+ // Accepts a Buffer or the Uint8Array that Puppeteer returns from screenshot().
14
+ export function pngSize(bytes) {
15
+ const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
16
+ if (buffer.length < 24 || buffer.toString('latin1', 1, 4) !== 'PNG') throw new Error('Not a PNG image');
17
+ return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
18
+ }
19
+
20
+ function optionValue(args, name) {
21
+ const i = args.indexOf(name);
22
+ if (i === -1) return null;
23
+ const value = args[i + 1];
24
+ if (value === undefined || value.startsWith('--')) throw new Error(`Missing value after ${name}`);
25
+ return value;
26
+ }
27
+
28
+ export function parseViewport(args) {
29
+ const size = optionValue(args, '--viewport');
30
+ const scale = optionValue(args, '--scale');
31
+ const isMobile = args.includes('--mobile');
32
+ if (size === null) {
33
+ if (isMobile || scale !== null) throw new Error('--mobile and --scale need --viewport <width>x<height>');
34
+ return null;
35
+ }
36
+ const match = /^([1-9]\d{0,4})x([1-9]\d{0,4})$/.exec(size);
37
+ if (!match) throw new Error(`Invalid --viewport value: ${size}. Expected <width>x<height>, for example 375x667`);
38
+ const deviceScaleFactor = scale === null ? 1 : Number(scale);
39
+ if (!(deviceScaleFactor > 0 && deviceScaleFactor <= 8)) throw new Error(`Invalid --scale value: ${scale}. Expected a number from 0 (exclusive) to 8`);
40
+ return { width: Number(match[1]), height: Number(match[2]), deviceScaleFactor, mobile: isMobile };
41
+ }
42
+
43
+ export function stripViewportArgs(args) {
44
+ const stripped = [];
45
+ for (let i = 0; i < args.length; i += 1) {
46
+ if (VIEWPORT_OPTIONS_WITH_VALUES.has(args[i])) i += 1;
47
+ else if (!VIEWPORT_FLAGS.has(args[i])) stripped.push(args[i]);
48
+ }
49
+ return stripped;
50
+ }
51
+
52
+ const windowSize = page => page.evaluate(() => `${innerWidth}x${innerHeight}`);
53
+
54
+ // Chrome does not draw a hidden tab, and without a drawn frame the page keeps the size it was last
55
+ // given, so clearing the override is not enough there. Capturing one pixel makes Chrome draw.
56
+ async function restoreSize(page, session, original) {
57
+ for (let attempt = 0; attempt < 20; attempt += 1) {
58
+ if (await windowSize(page) === original) return;
59
+ await session.send('Page.captureScreenshot', { format: 'jpeg', quality: 1, clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 } });
60
+ await new Promise(resolve => setTimeout(resolve, 50));
61
+ }
62
+ throw new Error(`The page did not return to its own size (${original}) after the screen size was cleared. It is still ${await windowSize(page)}`);
63
+ }
64
+
65
+ // Runs the callback with a CDP session that holds the requested size, or no size at all.
66
+ async function withSession(page, viewport, callback) {
67
+ const session = await page.createCDPSession();
68
+ let original = null;
69
+ let failed = true;
70
+ try {
71
+ if (viewport) {
72
+ original = await windowSize(page);
73
+ await session.send('Emulation.setDeviceMetricsOverride', viewport);
74
+ if (viewport.mobile) await session.send('Emulation.setTouchEmulationEnabled', { enabled: true });
75
+ }
76
+ const result = await callback(session);
77
+ failed = false;
78
+ return result;
79
+ } finally {
80
+ // Detaching drops the overrides, but not always before the next command looks at the page.
81
+ if (viewport?.mobile) await session.send('Emulation.setTouchEmulationEnabled', { enabled: false }).catch(() => {});
82
+ if (viewport) await session.send('Emulation.clearDeviceMetricsOverride').catch(() => {});
83
+ // A size that outlives its command is the silent failure this module exists to prevent, so it
84
+ // is an error. It must not replace the error of a command that already failed.
85
+ const restored = original === null ? null : await restoreSize(page, session, original).then(() => null, error => error);
86
+ await session.detach().catch(() => {});
87
+ if (restored && !failed) throw restored;
88
+ }
89
+ }
90
+
91
+ export async function withViewport(page, viewport, callback) {
92
+ if (!viewport) return callback();
93
+ return withSession(page, viewport, () => callback());
94
+ }
95
+
96
+ // Captures the viewport, the full page, or one element as PNG bytes, at the requested size.
97
+ //
98
+ // The capture is sent on the same session that holds the size. A capture sent on another session,
99
+ // which is what page.screenshot() does, honours the width but not the scale. The element is located
100
+ // by its position and captured beyond the viewport, because Puppeteer's element capture first waits
101
+ // for an IntersectionObserver that never fires on a background tab.
102
+ export async function capturePage(page, { viewport = null, fullPage = false, selector = null } = {}) {
103
+ if (fullPage && selector) throw new Error('Use only one of --full or --selector');
104
+ return withSession(page, viewport, async (session) => {
105
+ const layoutWidth = () => page.evaluate(() => innerWidth);
106
+ const before = viewport ? await layoutWidth() : null;
107
+ let clip = null;
108
+ if (selector) {
109
+ const box = await page.evaluate((query) => {
110
+ const node = document.querySelector(query);
111
+ if (!node) return null;
112
+ const rect = node.getBoundingClientRect();
113
+ return { x: rect.x + scrollX, y: rect.y + scrollY, width: rect.width, height: rect.height };
114
+ }, selector);
115
+ if (!box) throw new Error(`No element matches ${selector}`);
116
+ if (!(box.width > 0 && box.height > 0)) throw new Error(`Element ${selector} has no visible size`);
117
+ clip = { ...box, scale: 1 };
118
+ }
119
+ // A full-page capture has no clip: Chrome then captures the whole document, without the scrollbar gutter.
120
+ // Chrome drops the page's scrollbar for a capture beyond the viewport and does not bring it back.
121
+ // That is left alone: restoring it takes a resize the page can see.
122
+ const { data } = await session.send('Page.captureScreenshot', {
123
+ format: 'png', ...(clip ? { clip } : {}), captureBeyondViewport: Boolean(clip || fullPage),
124
+ });
125
+ const image = Buffer.from(data, 'base64');
126
+ // A capture at the wrong size looks plausible and misleads every measurement taken from it,
127
+ // so the requested size must still hold after the capture and must show in the image.
128
+ const after = viewport ? await layoutWidth() : null;
129
+ if (after !== before) throw new Error(`The page width changed from ${before} to ${after} px during the capture`);
130
+ const actual = pngSize(image);
131
+ const expected = expectedImageSize(viewport, { fullPage, selector });
132
+ if (expected && (actual.width !== expected.width || actual.height !== expected.height)) {
133
+ throw new Error(`Screenshot is ${actual.width}x${actual.height}, but --viewport asked for ${expected.width}x${expected.height}`);
134
+ }
135
+ return image;
136
+ });
137
+ }
138
+
139
+ // What the image must measure when the request fixes its size. A full-page or element capture is as
140
+ // large as its content, so only a plain viewport capture has a size to hold it to.
141
+ export function expectedImageSize(viewport, { fullPage = false, selector = null } = {}) {
142
+ if (!viewport || fullPage || selector) return null;
143
+ return {
144
+ width: Math.round(viewport.width * viewport.deviceScaleFactor),
145
+ height: Math.round(viewport.height * viewport.deviceScaleFactor),
146
+ };
147
+ }
148
+
149
+ export const SESSION_SCOPED_NOTE = 'Note: an Emulation override ends with this command, because Chrome drops it when the CDP session that set it detaches. '
150
+ + 'For a screen size, pass --viewport <width>x<height> [--mobile] [--scale <n>] to screenshot, eval, or nav instead.';