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