@namzu/browser 0.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.
Files changed (74) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/LICENSE.md +110 -0
  3. package/README.md +149 -0
  4. package/dist/classifier.d.ts +70 -0
  5. package/dist/classifier.d.ts.map +1 -0
  6. package/dist/classifier.js +147 -0
  7. package/dist/classifier.js.map +1 -0
  8. package/dist/detect.d.ts +126 -0
  9. package/dist/detect.d.ts.map +1 -0
  10. package/dist/detect.js +282 -0
  11. package/dist/detect.js.map +1 -0
  12. package/dist/errors.d.ts +64 -0
  13. package/dist/errors.d.ts.map +1 -0
  14. package/dist/errors.js +99 -0
  15. package/dist/errors.js.map +1 -0
  16. package/dist/host.d.ts +167 -0
  17. package/dist/host.d.ts.map +1 -0
  18. package/dist/host.js +1024 -0
  19. package/dist/host.js.map +1 -0
  20. package/dist/index.d.ts +17 -0
  21. package/dist/index.d.ts.map +1 -0
  22. package/dist/index.js +10 -0
  23. package/dist/index.js.map +1 -0
  24. package/dist/page-scripts.d.ts +51 -0
  25. package/dist/page-scripts.d.ts.map +1 -0
  26. package/dist/page-scripts.js +123 -0
  27. package/dist/page-scripts.js.map +1 -0
  28. package/dist/policy.d.ts +61 -0
  29. package/dist/policy.d.ts.map +1 -0
  30. package/dist/policy.js +150 -0
  31. package/dist/policy.js.map +1 -0
  32. package/dist/profiles.d.ts +107 -0
  33. package/dist/profiles.d.ts.map +1 -0
  34. package/dist/profiles.js +312 -0
  35. package/dist/profiles.js.map +1 -0
  36. package/dist/relay.d.ts +27 -0
  37. package/dist/relay.d.ts.map +1 -0
  38. package/dist/relay.js +69 -0
  39. package/dist/relay.js.map +1 -0
  40. package/dist/snapshot.d.ts +101 -0
  41. package/dist/snapshot.d.ts.map +1 -0
  42. package/dist/snapshot.js +265 -0
  43. package/dist/snapshot.js.map +1 -0
  44. package/dist/windows-bridge-script.d.ts +29 -0
  45. package/dist/windows-bridge-script.d.ts.map +1 -0
  46. package/dist/windows-bridge-script.js +161 -0
  47. package/dist/windows-bridge-script.js.map +1 -0
  48. package/dist/windows-bridge.d.ts +120 -0
  49. package/dist/windows-bridge.d.ts.map +1 -0
  50. package/dist/windows-bridge.js +267 -0
  51. package/dist/windows-bridge.js.map +1 -0
  52. package/dist/windows-engine.d.ts +55 -0
  53. package/dist/windows-engine.d.ts.map +1 -0
  54. package/dist/windows-engine.js +154 -0
  55. package/dist/windows-engine.js.map +1 -0
  56. package/dist/wsl.d.ts +52 -0
  57. package/dist/wsl.d.ts.map +1 -0
  58. package/dist/wsl.js +134 -0
  59. package/dist/wsl.js.map +1 -0
  60. package/package.json +74 -0
  61. package/src/classifier.ts +191 -0
  62. package/src/detect.ts +432 -0
  63. package/src/errors.ts +121 -0
  64. package/src/host.ts +1217 -0
  65. package/src/index.ts +79 -0
  66. package/src/page-scripts.ts +154 -0
  67. package/src/policy.ts +190 -0
  68. package/src/profiles.ts +373 -0
  69. package/src/relay.ts +101 -0
  70. package/src/snapshot.ts +317 -0
  71. package/src/windows-bridge-script.ts +160 -0
  72. package/src/windows-bridge.ts +358 -0
  73. package/src/windows-engine.ts +208 -0
  74. package/src/wsl.ts +155 -0
package/dist/host.js ADDED
@@ -0,0 +1,1024 @@
1
+ import { randomBytes } from 'node:crypto';
2
+ import { canonicalizeBrowserOrigin, canonicalizeBrowserUrl, resolveNamzuHome } from '@namzu/sdk';
3
+ import { chromium, } from 'playwright-core';
4
+ import { classifyHumanRequired, isCredentialField, } from './classifier.js';
5
+ import { detectBrowserEnvironment, runnableBrowserPlan, } from './detect.js';
6
+ import { BrowserHumanRequiredError, BrowserOriginMismatchError, BrowserOutcomeUnknownError, BrowserSiteDeniedError, BrowserStaleRefError, BrowserUnavailableError, ProfileBusyError, } from './errors.js';
7
+ import { countCredentialFields, fieldFacts, focusedFieldFacts, } from './page-scripts.js';
8
+ import { BrowserSitePolicy, DEFAULT_BROWSER_SITE_RULES } from './policy.js';
9
+ import { BrowserLeaseStore, BrowserProfileError, BrowserProfileStore, DEFAULT_BROWSER_PROFILE, } from './profiles.js';
10
+ import { PLAYWRIGHT_CORE_VERSION, SnapshotPager, captureAriaTree, locateRef, renderAriaTree, } from './snapshot.js';
11
+ import { WindowsBridgeError } from './windows-bridge.js';
12
+ import { connectWindowsBrowser } from './windows-engine.js';
13
+ const DEFAULT_NAVIGATION_TIMEOUT_MS = 30_000;
14
+ const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
15
+ /** How long a history move waits for the document after it committed. */
16
+ const HISTORY_LOAD_WAIT_MS = 5_000;
17
+ const SNAPSHOT_PAGE_MAX = 20_000;
18
+ /** How long the host lets events (popups, downloads, dialogs) arrive after an action. */
19
+ const EVENT_SETTLE_MS = 150;
20
+ /** Smallest frame that can hold a CAPTCHA a person is meant to solve. */
21
+ const CAPTCHA_FRAME_MIN_PX = 30;
22
+ function firstLine(error) {
23
+ const text = error instanceof Error ? error.message : String(error);
24
+ return (text.split('\n')[0] ?? '').slice(0, 300);
25
+ }
26
+ /** The page's origin as the header shows it: canonical, or `null` for anything that is not a web page. */
27
+ function originOf(url) {
28
+ if (url === 'about:blank' || url === '')
29
+ return 'null';
30
+ const verdict = canonicalizeBrowserUrl(url);
31
+ if (verdict.ok)
32
+ return verdict.url === 'about:blank' ? 'null' : verdict.origin;
33
+ return 'null';
34
+ }
35
+ function withoutQuery(url) {
36
+ try {
37
+ const parsed = new URL(url);
38
+ return `${parsed.origin}${parsed.pathname}`;
39
+ }
40
+ catch {
41
+ return url;
42
+ }
43
+ }
44
+ function pngSize(data) {
45
+ if (data.length < 24)
46
+ return { width: 0, height: 0 };
47
+ const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
48
+ return { width: view.getUint32(16), height: view.getUint32(20) };
49
+ }
50
+ function quoteShort(value, max = 80) {
51
+ const flat = value.replace(/\s+/g, ' ').trim();
52
+ return JSON.stringify(flat.length > max ? `${flat.slice(0, max - 1)}…` : flat);
53
+ }
54
+ /** Keys that type nothing: allowed while a credential field has focus. */
55
+ const NON_TYPING_KEYS = new Set(['Tab', 'Shift+Tab', 'Escape', 'Enter']);
56
+ /**
57
+ * A {@link BrowserHost} that runs Chromium (or an installed Chrome or Edge)
58
+ * in this process with Playwright, on a persistent profile. Inside WSL it
59
+ * drives the Windows Chrome or Edge instead, through the PowerShell bridge
60
+ * (`windows-engine.ts`).
61
+ *
62
+ * Nothing starts at construction: the browser is launched by the first call
63
+ * that needs it, so mounting the tools costs nothing until the model uses
64
+ * them.
65
+ *
66
+ * What it enforces, whatever the gate allowed:
67
+ *
68
+ * - every `browser_act` call's `origin` equals the live page's, checked
69
+ * immediately before acting;
70
+ * - a page that a navigation, redirect, script or popup lands on must be
71
+ * allowed by the site rules at `read` or `act`, or be an address the caller
72
+ * asked to open this session, or `about:blank`. A top-level request to
73
+ * anything else is blocked before it is sent; a redirect is caught when it
74
+ * lands, and the tab is cleared to `about:blank`;
75
+ * - acting needs the live origin at `ask` or `act`;
76
+ * - a sign-in, second factor, CAPTCHA, bot wall or HTTP credential prompt
77
+ * stops the call with `browser_human_required`;
78
+ * - nothing is ever typed into a password or one-time-code field;
79
+ * - downloads are cancelled and reported; a leave-page prompt is answered so
80
+ * navigation proceeds; other dialogs wait for `browser_act dialog`.
81
+ */
82
+ export class PlaywrightBrowserHost {
83
+ id;
84
+ capabilities;
85
+ plan;
86
+ profile;
87
+ options;
88
+ policy;
89
+ sessionId;
90
+ pager;
91
+ context;
92
+ windows;
93
+ launching;
94
+ lease;
95
+ tabs = new Map();
96
+ tabOf = new WeakMap();
97
+ tabCounter = 0;
98
+ activeTabId;
99
+ ownPageOpening = false;
100
+ pendingDialog;
101
+ notes = [];
102
+ blanking = new Set();
103
+ refs = new Map();
104
+ constructor(options = {}) {
105
+ this.options = options;
106
+ this.profile = options.profile ?? DEFAULT_BROWSER_PROFILE;
107
+ this.sessionId = options.sessionId ?? `s${randomBytes(6).toString('hex')}`;
108
+ this.policy = new BrowserSitePolicy(options.sites ?? DEFAULT_BROWSER_SITE_RULES);
109
+ const detected = options.plan ??
110
+ detectBrowserEnvironment(options.env ?? process.env, options.platform ?? process.platform, undefined, {
111
+ ...(options.engine ? { engine: options.engine } : {}),
112
+ ...(options.headless ? { headless: options.headless } : {}),
113
+ ...(options.mode ? { mode: options.mode } : {}),
114
+ });
115
+ this.plan = runnableBrowserPlan(detected);
116
+ const pageChars = Math.min(options.snapshotMaxChars ?? SNAPSHOT_PAGE_MAX, SNAPSHOT_PAGE_MAX);
117
+ this.pager = new SnapshotPager(pageChars);
118
+ this.id = `playwright-${this.plan.engine === 'local' ? this.plan.browser : this.plan.engine}`;
119
+ this.capabilities = {
120
+ engine: this.plan.engine === 'local' ? `local-${this.plan.browser}` : this.plan.engine,
121
+ headless: this.plan.headless,
122
+ screenshot: true,
123
+ upload: true,
124
+ snapshotMaxChars: pageChars,
125
+ ...(this.plan.unavailableReason !== undefined
126
+ ? { unavailableReason: this.plan.unavailableReason }
127
+ : {}),
128
+ };
129
+ }
130
+ /** Warnings from engine detection, for the operator. */
131
+ get warnings() {
132
+ return this.plan.warnings;
133
+ }
134
+ /** Whether the browser is running now. */
135
+ get running() {
136
+ return this.context !== undefined;
137
+ }
138
+ // -------------------------------------------------------------------------
139
+ // Lifecycle
140
+ // -------------------------------------------------------------------------
141
+ async ensureContext() {
142
+ if (this.context)
143
+ return this.context;
144
+ if (!this.launching) {
145
+ this.launching = this.launch().finally(() => {
146
+ this.launching = undefined;
147
+ });
148
+ }
149
+ return this.launching;
150
+ }
151
+ async launch() {
152
+ const plan = this.plan;
153
+ if (plan.unavailableReason !== undefined)
154
+ throw new BrowserUnavailableError(plan.unavailableReason);
155
+ const context = plan.engine === 'local' ? await this.launchLocal(plan) : await this.launchWindows(plan);
156
+ this.context = context;
157
+ context.setDefaultTimeout(this.options.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
158
+ context.setDefaultNavigationTimeout(this.options.navigationTimeoutMs ?? DEFAULT_NAVIGATION_TIMEOUT_MS);
159
+ context.on('page', (page) => this.adopt(page));
160
+ context.on('close', () => this.forget(context));
161
+ context.browser()?.on('disconnected', () => this.forget(context));
162
+ // Before a top-level request leaves: a link, script or popup heading for
163
+ // a site the rules do not allow is stopped here, so its address (and
164
+ // anything a page smuggled into it) never reaches the network.
165
+ await context.route(() => true, (route) => this.screen(route));
166
+ for (const page of context.pages())
167
+ this.adopt(page, false);
168
+ return context;
169
+ }
170
+ home() {
171
+ return this.options.home ?? resolveNamzuHome({ env: this.options.env ?? process.env });
172
+ }
173
+ async launchLocal(plan) {
174
+ const home = this.home();
175
+ const profiles = new BrowserProfileStore(home);
176
+ const descriptor = profiles.ensureLocal(this.profile, plan.browser);
177
+ const lease = new BrowserLeaseStore(home).acquire(this.profile, this.sessionId, {
178
+ exclusive: true,
179
+ });
180
+ let context;
181
+ try {
182
+ context = await chromium.launchPersistentContext(descriptor.userDataDir, {
183
+ headless: plan.headless,
184
+ ...(plan.channel ? { channel: plan.channel } : {}),
185
+ ...(this.options.executablePath ? { executablePath: this.options.executablePath } : {}),
186
+ acceptDownloads: false,
187
+ // The terminal owns Ctrl-C; the browser closes with the host.
188
+ handleSIGINT: false,
189
+ ...(plan.headless ? {} : { viewport: null }),
190
+ timeout: 60_000,
191
+ });
192
+ }
193
+ catch (error) {
194
+ lease.release();
195
+ throw this.launchError(error);
196
+ }
197
+ this.lease = lease;
198
+ return context;
199
+ }
200
+ /**
201
+ * The Windows browser, through the PowerShell bridge. The profile lives on
202
+ * the Windows side; its descriptor here records where. Leases are shared:
203
+ * every namzu process on the profile drives the same browser, and the
204
+ * last one to let go closes it.
205
+ */
206
+ async launchWindows(plan) {
207
+ const home = this.home();
208
+ const profiles = new BrowserProfileStore(home);
209
+ const existing = profiles.get(this.profile);
210
+ if (existing && existing.engine !== 'windows-cdp') {
211
+ throw new BrowserProfileError(`Browser profile "${this.profile}" belongs to the ${existing.engine} engine, not the Windows browser. Use another profile name.`);
212
+ }
213
+ if (existing && existing.browser !== plan.browser) {
214
+ throw new BrowserProfileError(`Browser profile "${this.profile}" was made with ${existing.browser}, and this run would use ${plan.browser}. Use another profile name, or the browser the profile was made with.`);
215
+ }
216
+ const lease = new BrowserLeaseStore(home).acquire(this.profile, this.sessionId);
217
+ let connection;
218
+ try {
219
+ connection = await connectWindowsBrowser({
220
+ plan,
221
+ profile: this.profile,
222
+ ...(existing ? { userDataDir: existing.userDataDir } : {}),
223
+ closeOnExit: !this.options.keepOpen,
224
+ env: this.options.env ?? process.env,
225
+ ...(this.options.windowsLaunchTimeoutMs !== undefined
226
+ ? { timeoutMs: this.options.windowsLaunchTimeoutMs }
227
+ : {}),
228
+ onDownloadRefused: (name) => {
229
+ this.notes.push(`A download of ${quoteShort(name)} was cancelled: the browser does not download files.`);
230
+ },
231
+ });
232
+ }
233
+ catch (error) {
234
+ lease.release();
235
+ throw this.windowsLaunchError(plan, error);
236
+ }
237
+ try {
238
+ profiles.ensureWindows(this.profile, plan.browser, connection.userDataDir);
239
+ }
240
+ catch (error) {
241
+ lease.release();
242
+ await connection.detach().catch(() => undefined);
243
+ throw error;
244
+ }
245
+ this.lease = lease;
246
+ this.windows = connection;
247
+ return connection.context;
248
+ }
249
+ windowsLaunchError(plan, error) {
250
+ const name = plan.browser === 'chrome' ? 'Google Chrome' : 'Microsoft Edge';
251
+ if (error instanceof WindowsBridgeError) {
252
+ if (error.code === 'browser-exited')
253
+ return new ProfileBusyError(this.profile, []);
254
+ return new BrowserUnavailableError(`The Windows ${name} could not be started from WSL: ${error.message}`);
255
+ }
256
+ return new BrowserUnavailableError(`The Windows ${name} was started but could not be driven from WSL: ${firstLine(error)}`);
257
+ }
258
+ launchError(error) {
259
+ const text = error instanceof Error ? error.message : String(error);
260
+ if (/Executable doesn't exist|executable doesn't exist|browserType\.launch.*not found/i.test(text)) {
261
+ const which = this.plan.engine === 'local' && this.plan.browser !== 'chromium'
262
+ ? `The installed ${this.plan.browser === 'chrome' ? 'Google Chrome' : 'Microsoft Edge'} was not found where it should be.`
263
+ : `Playwright's Chromium for playwright-core ${PLAYWRIGHT_CORE_VERSION} is not installed.`;
264
+ return new BrowserUnavailableError(`${which} Run \`namzu browser install\` (or \`npx playwright-core@${PLAYWRIGHT_CORE_VERSION} install chromium\`).`);
265
+ }
266
+ if (/ProcessSingleton|SingletonLock|already in use|profile.*in use/i.test(text)) {
267
+ return new ProfileBusyError(this.profile, []);
268
+ }
269
+ if (/Missing X server|cannot open display|\$DISPLAY/i.test(text)) {
270
+ return new BrowserUnavailableError('The browser needs a display for a visible window and could not open one. Run headless, or under a desktop session.');
271
+ }
272
+ return new BrowserUnavailableError(`The browser could not start: ${firstLine(error)}`);
273
+ }
274
+ forget(context) {
275
+ if (this.context !== context)
276
+ return;
277
+ this.context = undefined;
278
+ const windows = this.windows;
279
+ this.windows = undefined;
280
+ if (windows)
281
+ void windows.detach().catch(() => undefined);
282
+ this.tabs.clear();
283
+ this.activeTabId = undefined;
284
+ this.pendingDialog = undefined;
285
+ this.refs = new Map();
286
+ this.lease?.release();
287
+ this.lease = undefined;
288
+ }
289
+ async initialize() {
290
+ // Deliberately nothing: the browser starts on first use.
291
+ }
292
+ /**
293
+ * Release this host's lease. The browser closes when that was the last
294
+ * lease on the profile, unless `keepOpen` was set.
295
+ */
296
+ async dispose() {
297
+ const lease = this.lease;
298
+ this.lease = undefined;
299
+ const last = lease ? lease.release().last : true;
300
+ if (last && !this.options.keepOpen) {
301
+ await this.close();
302
+ return;
303
+ }
304
+ // The Windows browser is shared with every other holder of the
305
+ // profile, or is to stay open: disconnect without closing it.
306
+ const context = this.context;
307
+ const windows = this.windows;
308
+ if (!context || !windows)
309
+ return;
310
+ this.windows = undefined;
311
+ this.forget(context);
312
+ await windows.detach().catch(() => undefined);
313
+ }
314
+ /** Close the browser now, whatever the leases say. */
315
+ async close() {
316
+ const context = this.context;
317
+ if (!context)
318
+ return;
319
+ const windows = this.windows;
320
+ this.windows = undefined;
321
+ this.forget(context);
322
+ if (windows)
323
+ await windows.close().catch(() => undefined);
324
+ else
325
+ await context.close().catch(() => undefined);
326
+ }
327
+ // -------------------------------------------------------------------------
328
+ // Tabs and events
329
+ // -------------------------------------------------------------------------
330
+ adopt(page, announce = true) {
331
+ const known = this.tabOf.get(page);
332
+ if (known)
333
+ return known;
334
+ this.tabCounter += 1;
335
+ const tab = { id: `t${this.tabCounter}`, page };
336
+ this.tabs.set(tab.id, tab);
337
+ this.tabOf.set(page, tab);
338
+ if (this.activeTabId === undefined)
339
+ this.activeTabId = tab.id;
340
+ if (announce && !this.ownPageOpening) {
341
+ this.notes.push(`The page opened a new tab, ${tab.id}; it is not the active tab. Use tabs list or select to look at it.`);
342
+ }
343
+ page.on('framenavigated', (frame) => {
344
+ if (frame === page.mainFrame())
345
+ this.checkLanding(tab);
346
+ });
347
+ page.on('response', (response) => {
348
+ try {
349
+ if (response.request().isNavigationRequest() && response.frame() === page.mainFrame()) {
350
+ tab.status = response.status();
351
+ }
352
+ }
353
+ catch {
354
+ // A response without a frame (a service worker's) says nothing about the page.
355
+ }
356
+ });
357
+ page.on('dialog', (dialog) => this.onDialog(tab, dialog));
358
+ page.on('download', (download) => {
359
+ const name = download.suggestedFilename();
360
+ this.notes.push(`A download of ${quoteShort(name)} was cancelled: the browser does not download files.`);
361
+ void download.cancel().catch(() => undefined);
362
+ });
363
+ page.on('close', () => {
364
+ this.tabs.delete(tab.id);
365
+ if (this.pendingDialog?.tab === tab)
366
+ this.pendingDialog = undefined;
367
+ if (this.activeTabId === tab.id)
368
+ this.activeTabId = [...this.tabs.keys()].pop();
369
+ });
370
+ return tab;
371
+ }
372
+ onDialog(tab, dialog) {
373
+ if (dialog.type() === 'beforeunload') {
374
+ // The call that left the page was approved; a "leave site?" prompt
375
+ // would otherwise hold the navigation until it timed out.
376
+ void dialog.accept().catch(() => undefined);
377
+ this.notes.push('The page asked before leaving; it was left.');
378
+ return;
379
+ }
380
+ if (this.pendingDialog) {
381
+ void dialog.dismiss().catch(() => undefined);
382
+ return;
383
+ }
384
+ this.pendingDialog = { tab, dialog };
385
+ this.notes.push(`A ${dialog.type()} dialog is open on tab ${tab.id}. Take a snapshot to read it, then answer it with browser_act dialog.`);
386
+ }
387
+ /** The route handler: stop top-level navigations the policy does not allow. */
388
+ async screen(route) {
389
+ const request = route.request();
390
+ let topLevel = false;
391
+ if (request.isNavigationRequest()) {
392
+ try {
393
+ topLevel = request.frame().parentFrame() === null;
394
+ }
395
+ catch {
396
+ // A popup's first request is issued before its frame exists; it is
397
+ // the top-level document of the new tab.
398
+ topLevel = true;
399
+ }
400
+ }
401
+ if (topLevel) {
402
+ const verdict = this.policy.landing(request.url());
403
+ if (!verdict.allowed) {
404
+ this.notes.push(`A navigation to ${verdict.origin} was blocked before it was sent: ${verdict.reason}. To go there, open it with navigate.`);
405
+ // `aborted`, not `blockedbyclient`: Chromium commits an error page
406
+ // for the latter, which would replace the page the tab was on.
407
+ await route.abort('aborted').catch(() => undefined);
408
+ return;
409
+ }
410
+ }
411
+ await route.fallback().catch(() => undefined);
412
+ }
413
+ /** After a navigation lands: clear the tab if the policy does not allow where it is. */
414
+ checkLanding(tab) {
415
+ const url = tab.page.url();
416
+ const verdict = this.policy.landing(url);
417
+ if (verdict.allowed)
418
+ return;
419
+ this.notes.push(`Tab ${tab.id} ended up on ${verdict.origin}: ${verdict.reason}. It was cleared to about:blank.`);
420
+ const blank = tab.page
421
+ .goto('about:blank')
422
+ .catch(() => undefined)
423
+ .finally(() => this.blanking.delete(blank));
424
+ this.blanking.add(blank);
425
+ }
426
+ async settle() {
427
+ await new Promise((resolve) => setTimeout(resolve, EVENT_SETTLE_MS));
428
+ while (this.blanking.size > 0)
429
+ await Promise.all([...this.blanking]);
430
+ }
431
+ async activeTab() {
432
+ const context = await this.ensureContext();
433
+ const current = this.activeTabId ? this.tabs.get(this.activeTabId) : undefined;
434
+ if (current && !current.page.isClosed())
435
+ return current;
436
+ const page = await this.openOwnPage(context);
437
+ const tab = this.adopt(page, false);
438
+ this.activeTabId = tab.id;
439
+ return tab;
440
+ }
441
+ async openOwnPage(context) {
442
+ this.ownPageOpening = true;
443
+ try {
444
+ return await context.newPage();
445
+ }
446
+ finally {
447
+ this.ownPageOpening = false;
448
+ }
449
+ }
450
+ drainNotes() {
451
+ if (this.notes.length === 0)
452
+ return undefined;
453
+ const text = this.notes.join(' ');
454
+ this.notes.length = 0;
455
+ return text;
456
+ }
457
+ async title(tab) {
458
+ if (this.pendingDialog?.tab === tab)
459
+ return '';
460
+ return Promise.race([
461
+ tab.page.title().catch(() => ''),
462
+ new Promise((resolve) => setTimeout(() => resolve(''), 1000)),
463
+ ]);
464
+ }
465
+ async pageInfo(tab) {
466
+ const url = tab.page.url();
467
+ return { origin: originOf(url), url, title: await this.title(tab), tab: tab.id };
468
+ }
469
+ result(extra) {
470
+ const message = this.drainNotes();
471
+ return { ...extra, ...(message !== undefined ? { message } : {}) };
472
+ }
473
+ // -------------------------------------------------------------------------
474
+ // Human handoff
475
+ // -------------------------------------------------------------------------
476
+ loginCommandFor(url) {
477
+ const target = withoutQuery(url);
478
+ return this.options.loginCommand
479
+ ? this.options.loginCommand(this.profile, target)
480
+ : `namzu browser login ${this.profile} ${target}`;
481
+ }
482
+ humanRequired(reason, tab) {
483
+ const url = tab.page.url();
484
+ return new BrowserHumanRequiredError(reason, originOf(url), {
485
+ profile: this.profile,
486
+ loginCommand: this.loginCommandFor(url),
487
+ });
488
+ }
489
+ /** Throw `browser_human_required` if the page needs a person. */
490
+ async checkHuman(tab) {
491
+ const page = tab.page;
492
+ const url = page.url();
493
+ if (originOf(url) === 'null' || this.pendingDialog?.tab === tab)
494
+ return;
495
+ const counts = await page
496
+ .evaluate(countCredentialFields)
497
+ .catch(() => ({ passwordFields: 0, oneTimeCodeFields: 0 }));
498
+ const frameUrls = [];
499
+ for (const frame of page.frames()) {
500
+ if (frame === page.mainFrame())
501
+ continue;
502
+ try {
503
+ const element = await frame.frameElement();
504
+ const box = await element.boundingBox();
505
+ if (box && box.width >= CAPTCHA_FRAME_MIN_PX && box.height >= CAPTCHA_FRAME_MIN_PX) {
506
+ frameUrls.push(frame.url());
507
+ }
508
+ }
509
+ catch {
510
+ // A frame that went away while we looked is not a challenge.
511
+ }
512
+ }
513
+ const reason = classifyHumanRequired({
514
+ url,
515
+ title: await this.title(tab),
516
+ ...(tab.status !== undefined ? { status: tab.status } : {}),
517
+ ...counts,
518
+ frameUrls,
519
+ }, this.options.signInAddresses ? { signInAddresses: this.options.signInAddresses } : {});
520
+ if (reason)
521
+ throw this.humanRequired(reason, tab);
522
+ }
523
+ // -------------------------------------------------------------------------
524
+ // Calls
525
+ // -------------------------------------------------------------------------
526
+ async guarded(signal, run) {
527
+ if (signal?.aborted)
528
+ throw new Error('The browser call was cancelled.');
529
+ if (!signal)
530
+ return run();
531
+ let onAbort;
532
+ const aborted = new Promise((_, reject) => {
533
+ onAbort = () => reject(new Error('The browser call was cancelled.'));
534
+ signal.addEventListener('abort', onAbort, { once: true });
535
+ });
536
+ try {
537
+ return await Promise.race([run(), aborted]);
538
+ }
539
+ finally {
540
+ if (onAbort)
541
+ signal.removeEventListener('abort', onAbort);
542
+ }
543
+ }
544
+ async observe(action, options) {
545
+ return this.guarded(options?.signal, () => this.runObserve(action));
546
+ }
547
+ async act(action, options) {
548
+ return this.guarded(options?.signal, () => this.runAct(action));
549
+ }
550
+ async runObserve(action) {
551
+ switch (action.action) {
552
+ case 'navigate':
553
+ return this.navigate(await this.activeTab(), action.url);
554
+ case 'back':
555
+ case 'forward':
556
+ case 'reload':
557
+ return this.history(action.action);
558
+ case 'snapshot':
559
+ return this.snapshot(action.ref, action.cursor);
560
+ case 'screenshot':
561
+ return this.screenshot(action.ref, action.fullPage);
562
+ case 'scroll':
563
+ return this.scroll(action.direction, action.ref, action.amount);
564
+ case 'wait_for':
565
+ return this.waitFor(action);
566
+ case 'tabs':
567
+ return this.tabsCall(action);
568
+ }
569
+ }
570
+ async navigate(tab, rawUrl) {
571
+ const verdict = canonicalizeBrowserUrl(rawUrl);
572
+ if (!verdict.ok)
573
+ throw new BrowserSiteDeniedError('', `The address was refused: ${verdict.reason}`);
574
+ if (verdict.url !== 'about:blank') {
575
+ const level = this.policy.levelOf(verdict.origin);
576
+ if (level === 'deny')
577
+ throw new BrowserSiteDeniedError(verdict.origin);
578
+ this.policy.approve(verdict.origin);
579
+ }
580
+ await this.dismissPendingDialog(tab);
581
+ tab.status = undefined;
582
+ try {
583
+ await tab.page.goto(verdict.url, { waitUntil: 'domcontentloaded' });
584
+ }
585
+ catch (error) {
586
+ if (!/ERR_BLOCKED_BY_CLIENT|ERR_ABORTED|Download is starting/.test(firstLine(error))) {
587
+ throw new Error(`Could not open ${verdict.url}: ${firstLine(error)}`);
588
+ }
589
+ }
590
+ return this.afterNavigation(tab);
591
+ }
592
+ async afterNavigation(tab) {
593
+ await this.settle();
594
+ this.checkLanding(tab);
595
+ await this.settle();
596
+ await this.checkHuman(tab);
597
+ return this.result({ page: await this.pageInfo(tab) });
598
+ }
599
+ async history(which) {
600
+ const tab = await this.activeTab();
601
+ await this.dismissPendingDialog(tab);
602
+ tab.status = undefined;
603
+ // `commit`, then the document as a bonus: a page restored from the
604
+ // back-forward cache fires no `domcontentloaded`, so waiting for it
605
+ // timed out after a history move that had long finished (measured
606
+ // with the Windows engine: 30 s, then a failure, on a page that was
607
+ // already back).
608
+ const options = { waitUntil: 'commit' };
609
+ const before = tab.page.url();
610
+ let response = true;
611
+ try {
612
+ response =
613
+ which === 'back'
614
+ ? await tab.page.goBack(options)
615
+ : which === 'forward'
616
+ ? await tab.page.goForward(options)
617
+ : await tab.page.reload(options);
618
+ }
619
+ catch (error) {
620
+ if (!/ERR_BLOCKED_BY_CLIENT|ERR_ABORTED/.test(firstLine(error)))
621
+ throw error;
622
+ }
623
+ if (response !== null) {
624
+ await tab.page
625
+ .waitForLoadState('domcontentloaded', { timeout: HISTORY_LOAD_WAIT_MS })
626
+ .catch(() => undefined);
627
+ }
628
+ // `null` is also what a restore from the back-forward cache returns:
629
+ // no network response. Only an unchanged address means nowhere to go.
630
+ if (response === null && which !== 'reload' && tab.page.url() === before) {
631
+ this.notes.push(`There is no page to go ${which} to.`);
632
+ }
633
+ return this.afterNavigation(tab);
634
+ }
635
+ async dismissPendingDialog(tab) {
636
+ const pending = this.pendingDialog;
637
+ if (!pending || pending.tab !== tab)
638
+ return;
639
+ this.pendingDialog = undefined;
640
+ await pending.dialog.dismiss().catch(() => undefined);
641
+ this.notes.push('The open dialog was dismissed.');
642
+ }
643
+ async takeSnapshot(tab, ref) {
644
+ const pending = this.pendingDialog;
645
+ if (pending && pending.tab === tab) {
646
+ const dialog = pending.dialog;
647
+ const lines = [
648
+ `- dialog (${dialog.type()}) ${JSON.stringify(dialog.message().replace(/\s+/g, ' ').trim())}`,
649
+ ];
650
+ if (dialog.type() === 'prompt')
651
+ lines.push(` - /default: ${JSON.stringify(dialog.defaultValue())}`);
652
+ lines.push(' - (the page is paused until the dialog is answered)');
653
+ return { page: await this.pageInfo(tab), text: lines.join('\n') };
654
+ }
655
+ const { nodes, hidden, redact } = await captureAriaTree(tab.page, this.options.actionTimeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS);
656
+ const whole = renderAriaTree(nodes, hidden, undefined, redact);
657
+ if (!whole)
658
+ throw new Error('The page could not be read.');
659
+ this.refs = whole.refs;
660
+ let text = whole.text;
661
+ if (ref !== undefined) {
662
+ const region = renderAriaTree(nodes, hidden, ref, redact);
663
+ if (!region || !whole.refs.has(ref))
664
+ throw new BrowserStaleRefError(ref);
665
+ text = region.text;
666
+ }
667
+ if (text.trim() === '')
668
+ text = '(nothing readable on this page)';
669
+ const first = this.pager.start(text);
670
+ return {
671
+ page: await this.pageInfo(tab),
672
+ text: first.text,
673
+ ...(first.nextCursor !== undefined ? { nextCursor: first.nextCursor } : {}),
674
+ };
675
+ }
676
+ async snapshot(ref, cursor) {
677
+ const tab = await this.activeTab();
678
+ if (cursor !== undefined) {
679
+ const next = this.pager.resume(cursor);
680
+ if (!next) {
681
+ throw new Error('That cursor belongs to an older snapshot. Take a new snapshot and page through it.');
682
+ }
683
+ return this.result({
684
+ snapshot: {
685
+ page: await this.pageInfo(tab),
686
+ text: next.text,
687
+ ...(next.nextCursor !== undefined ? { nextCursor: next.nextCursor } : {}),
688
+ },
689
+ });
690
+ }
691
+ await this.settle();
692
+ return this.result({ snapshot: await this.takeSnapshot(tab, ref) });
693
+ }
694
+ async resolveRef(tab, ref) {
695
+ if (!this.refs.has(ref))
696
+ throw new BrowserStaleRefError(ref);
697
+ const locator = locateRef(tab.page, ref);
698
+ let count = 0;
699
+ try {
700
+ count = await locator.count();
701
+ }
702
+ catch {
703
+ count = 0;
704
+ }
705
+ if (count !== 1)
706
+ throw new BrowserStaleRefError(ref);
707
+ return locator;
708
+ }
709
+ async screenshot(ref, fullPage) {
710
+ const tab = await this.activeTab();
711
+ if (this.pendingDialog?.tab === tab) {
712
+ throw new Error('A dialog is open; answer it with browser_act dialog before taking a screenshot.');
713
+ }
714
+ const data = ref !== undefined
715
+ ? await (await this.resolveRef(tab, ref)).screenshot({ type: 'png' })
716
+ : await tab.page.screenshot({ type: 'png', fullPage: fullPage === true });
717
+ const bytes = new Uint8Array(data);
718
+ const size = pngSize(bytes);
719
+ return this.result({
720
+ screenshot: {
721
+ page: await this.pageInfo(tab),
722
+ data: bytes,
723
+ mimeType: 'image/png',
724
+ width: size.width,
725
+ height: size.height,
726
+ },
727
+ });
728
+ }
729
+ async scroll(direction, ref, amount) {
730
+ const tab = await this.activeTab();
731
+ const screens = amount ?? 1;
732
+ const vector = { up: [0, -1], down: [0, 1], left: [-1, 0], right: [1, 0] }[direction];
733
+ const [dx, dy] = vector;
734
+ if (ref !== undefined) {
735
+ const locator = await this.resolveRef(tab, ref);
736
+ await locator.evaluate((el, [x, y, n]) => {
737
+ el.scrollBy({
738
+ left: x * el.clientWidth * 0.9 * n,
739
+ top: y * el.clientHeight * 0.9 * n,
740
+ });
741
+ }, [dx, dy, screens]);
742
+ }
743
+ else {
744
+ await tab.page.evaluate(([x, y, n]) => {
745
+ window.scrollBy({
746
+ left: x * window.innerWidth * 0.9 * n,
747
+ top: y * window.innerHeight * 0.9 * n,
748
+ });
749
+ }, [dx, dy, screens]);
750
+ }
751
+ this.notes.unshift(`Scrolled ${direction}.`);
752
+ return this.result({ page: await this.pageInfo(tab) });
753
+ }
754
+ async waitFor(action) {
755
+ const tab = await this.activeTab();
756
+ const timeout = Math.min(action.timeMs ?? 30_000, 30_000);
757
+ if (this.pendingDialog?.tab === tab) {
758
+ return this.result({ page: await this.pageInfo(tab) });
759
+ }
760
+ if (action.text !== undefined || action.textGone !== undefined) {
761
+ const text = (action.text ?? action.textGone);
762
+ const state = action.text !== undefined ? 'visible' : 'hidden';
763
+ try {
764
+ await tab.page.getByText(text).first().waitFor({ state, timeout });
765
+ this.notes.unshift(action.text !== undefined
766
+ ? `${quoteShort(text)} is on the page.`
767
+ : `${quoteShort(text)} is gone.`);
768
+ }
769
+ catch {
770
+ this.notes.unshift(action.text !== undefined
771
+ ? `${quoteShort(text)} did not appear within ${timeout} ms.`
772
+ : `${quoteShort(text)} was still there after ${timeout} ms.`);
773
+ }
774
+ }
775
+ else {
776
+ await tab.page.waitForTimeout(timeout);
777
+ this.notes.unshift(`Waited ${timeout} ms.`);
778
+ }
779
+ return this.result({ page: await this.pageInfo(tab) });
780
+ }
781
+ async tabsCall(action) {
782
+ const context = await this.ensureContext();
783
+ await this.activeTab();
784
+ switch (action.op) {
785
+ case 'list':
786
+ return this.result({ tabs: await this.tabList() });
787
+ case 'select': {
788
+ const tab = this.tabs.get(action.tab ?? '');
789
+ if (!tab)
790
+ throw new Error(`There is no tab ${action.tab}. List the tabs to see their ids.`);
791
+ this.activeTabId = tab.id;
792
+ await tab.page.bringToFront().catch(() => undefined);
793
+ this.refs = new Map();
794
+ return this.result({ page: await this.pageInfo(tab) });
795
+ }
796
+ case 'close': {
797
+ const tab = this.tabs.get(action.tab ?? '');
798
+ if (!tab)
799
+ throw new Error(`There is no tab ${action.tab}. List the tabs to see their ids.`);
800
+ await tab.page.close().catch(() => undefined);
801
+ this.tabs.delete(tab.id);
802
+ if (this.activeTabId === tab.id) {
803
+ this.activeTabId = [...this.tabs.keys()].pop();
804
+ this.refs = new Map();
805
+ }
806
+ return this.result({ tabs: await this.tabList() });
807
+ }
808
+ case 'new': {
809
+ const page = await this.openOwnPage(context);
810
+ const tab = this.adopt(page, false);
811
+ this.activeTabId = tab.id;
812
+ this.refs = new Map();
813
+ if (action.url === undefined || action.url === 'about:blank') {
814
+ return this.result({ page: await this.pageInfo(tab) });
815
+ }
816
+ return this.navigate(tab, action.url);
817
+ }
818
+ }
819
+ }
820
+ async tabList() {
821
+ const out = [];
822
+ for (const tab of this.tabs.values()) {
823
+ if (tab.page.isClosed())
824
+ continue;
825
+ out.push({ ...(await this.pageInfo(tab)), active: tab.id === this.activeTabId });
826
+ }
827
+ return out;
828
+ }
829
+ // -------------------------------------------------------------------------
830
+ // Acting
831
+ // -------------------------------------------------------------------------
832
+ async guardField(tab, locator) {
833
+ const facts = await locator.evaluate(fieldFacts);
834
+ if (isCredentialField(facts))
835
+ throw this.humanRequired('credential-field', tab);
836
+ return facts;
837
+ }
838
+ async runAct(action) {
839
+ const tab = await this.activeTab();
840
+ await this.settle();
841
+ const expected = canonicalizeBrowserOrigin(action.origin);
842
+ const live = originOf(tab.page.url());
843
+ if (!expected.ok || expected.origin !== live) {
844
+ throw new BrowserOriginMismatchError(expected.ok ? expected.origin : action.origin, live === 'null' ? 'about:blank' : live);
845
+ }
846
+ if (!this.policy.canAct(live)) {
847
+ throw new BrowserSiteDeniedError(live, `${live} may be read but not changed under the site rules.`);
848
+ }
849
+ if (action.action === 'dialog')
850
+ return this.answerDialog(tab, action);
851
+ if (this.pendingDialog?.tab === tab) {
852
+ throw new Error('A dialog is open on this tab; answer it with browser_act dialog first.');
853
+ }
854
+ await this.perform(tab, action);
855
+ await this.settle();
856
+ this.checkLanding(tab);
857
+ await this.settle();
858
+ await this.checkHuman(tab);
859
+ const after = this.tabs.get(tab.id) ?? tab;
860
+ if (action.snapshot)
861
+ return this.result({ snapshot: await this.takeSnapshot(after) });
862
+ return this.result({ page: await this.pageInfo(after) });
863
+ }
864
+ async answerDialog(tab, action) {
865
+ const pending = this.pendingDialog;
866
+ if (!pending || pending.tab !== tab)
867
+ throw new Error('No dialog is open on this tab.');
868
+ this.pendingDialog = undefined;
869
+ try {
870
+ if (action.accept)
871
+ await pending.dialog.accept(action.promptText);
872
+ else
873
+ await pending.dialog.dismiss();
874
+ }
875
+ catch (error) {
876
+ throw new BrowserOutcomeUnknownError('dialog', error);
877
+ }
878
+ this.notes.unshift(action.accept ? 'The dialog was accepted.' : 'The dialog was dismissed.');
879
+ await this.settle();
880
+ this.checkLanding(tab);
881
+ await this.settle();
882
+ if (action.snapshot)
883
+ return this.result({ snapshot: await this.takeSnapshot(tab) });
884
+ return this.result({ page: await this.pageInfo(tab) });
885
+ }
886
+ /**
887
+ * Do the action. Everything that can refuse — refs, credential fields,
888
+ * actionability — is checked before anything happens; a failure after
889
+ * the first change is `browser_outcome_unknown`.
890
+ */
891
+ async perform(tab, action) {
892
+ switch (action.action) {
893
+ case 'click': {
894
+ const locator = await this.resolveRef(tab, action.ref);
895
+ await locator.click({ trial: true });
896
+ await this.unknownOnFailure('click', () => action.doubleClick ? locator.dblclick() : locator.click());
897
+ return;
898
+ }
899
+ case 'hover': {
900
+ const locator = await this.resolveRef(tab, action.ref);
901
+ await locator.hover({ trial: true });
902
+ await this.unknownOnFailure('hover', () => locator.hover());
903
+ return;
904
+ }
905
+ case 'type': {
906
+ const locator = await this.resolveRef(tab, action.ref);
907
+ await this.guardField(tab, locator);
908
+ await locator.click({ trial: true });
909
+ await this.unknownOnFailure('type', async () => {
910
+ await locator.fill(action.text);
911
+ if (action.submit)
912
+ await locator.press('Enter');
913
+ });
914
+ return;
915
+ }
916
+ case 'fill_form': {
917
+ const plan = [];
918
+ for (const field of action.fields) {
919
+ const locator = await this.resolveRef(tab, field.ref);
920
+ const facts = await this.guardField(tab, locator);
921
+ if (facts.kind === 'file') {
922
+ throw new Error(`${field.ref} is a file input; use browser_act upload for it.`);
923
+ }
924
+ plan.push({ locator, facts, value: field.value });
925
+ }
926
+ await this.unknownOnFailure('fill_form', async () => {
927
+ for (const step of plan) {
928
+ if (step.facts.kind === 'checkbox' || step.facts.kind === 'radio') {
929
+ await step.locator.setChecked(step.value === 'true');
930
+ }
931
+ else if (step.facts.kind === 'select') {
932
+ await step.locator
933
+ .selectOption([{ label: step.value }])
934
+ .catch(() => step.locator.selectOption(step.value));
935
+ }
936
+ else {
937
+ await step.locator.fill(step.value);
938
+ }
939
+ }
940
+ });
941
+ return;
942
+ }
943
+ case 'select': {
944
+ const locator = await this.resolveRef(tab, action.ref);
945
+ await this.unknownOnFailure('select', () => locator.selectOption([...action.values]));
946
+ return;
947
+ }
948
+ case 'press': {
949
+ if (action.ref !== undefined) {
950
+ const locator = await this.resolveRef(tab, action.ref);
951
+ const facts = await locator.evaluate(fieldFacts);
952
+ if (isCredentialField(facts) && !NON_TYPING_KEYS.has(action.key)) {
953
+ throw this.humanRequired('credential-field', tab);
954
+ }
955
+ await this.unknownOnFailure('press', () => locator.press(action.key));
956
+ return;
957
+ }
958
+ const focused = await tab.page.evaluate(focusedFieldFacts).catch(() => null);
959
+ if (focused && isCredentialField(focused) && !NON_TYPING_KEYS.has(action.key)) {
960
+ throw this.humanRequired('credential-field', tab);
961
+ }
962
+ await this.unknownOnFailure('press', () => tab.page.keyboard.press(action.key));
963
+ return;
964
+ }
965
+ case 'upload': {
966
+ const locator = await this.resolveRef(tab, action.ref);
967
+ const facts = await locator.evaluate(fieldFacts);
968
+ if (facts.kind === 'file') {
969
+ await this.unknownOnFailure('upload', () => locator.setInputFiles(action.path));
970
+ return;
971
+ }
972
+ await locator.click({ trial: true });
973
+ await this.unknownOnFailure('upload', async () => {
974
+ const [chooser] = await Promise.all([
975
+ tab.page.waitForEvent('filechooser'),
976
+ locator.click(),
977
+ ]);
978
+ await chooser.setFiles(action.path);
979
+ });
980
+ return;
981
+ }
982
+ case 'dialog':
983
+ return;
984
+ }
985
+ }
986
+ /**
987
+ * Run the change. A failure once it has started is `outcome unknown`. A
988
+ * dialog the action opens ends the wait: the page is paused until the
989
+ * dialog is answered, and so is anything Playwright was still waiting for.
990
+ */
991
+ async unknownOnFailure(action, run) {
992
+ const running = run();
993
+ let timer;
994
+ const dialogOpened = new Promise((resolve) => {
995
+ timer = setInterval(() => {
996
+ if (this.pendingDialog)
997
+ resolve('dialog');
998
+ }, 50);
999
+ });
1000
+ try {
1001
+ const outcome = await Promise.race([running, dialogOpened]);
1002
+ if (outcome === 'dialog')
1003
+ running.catch(() => undefined);
1004
+ }
1005
+ catch (error) {
1006
+ throw new BrowserOutcomeUnknownError(action, error);
1007
+ }
1008
+ finally {
1009
+ clearInterval(timer);
1010
+ }
1011
+ }
1012
+ // -------------------------------------------------------------------------
1013
+ // Labels
1014
+ // -------------------------------------------------------------------------
1015
+ describeRef(ref) {
1016
+ return this.refs.get(ref);
1017
+ }
1018
+ session() {
1019
+ const tab = this.activeTabId ? this.tabs.get(this.activeTabId) : undefined;
1020
+ const origin = tab && !tab.page.isClosed() ? originOf(tab.page.url()) : 'null';
1021
+ return { profile: this.profile, ...(origin !== 'null' ? { origin } : {}) };
1022
+ }
1023
+ }
1024
+ //# sourceMappingURL=host.js.map