@namzu/browser 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/dist/classifier.d.ts +22 -1
  3. package/dist/classifier.d.ts.map +1 -1
  4. package/dist/classifier.js +30 -7
  5. package/dist/classifier.js.map +1 -1
  6. package/dist/errors.d.ts +19 -1
  7. package/dist/errors.d.ts.map +1 -1
  8. package/dist/errors.js +26 -0
  9. package/dist/errors.js.map +1 -1
  10. package/dist/host.d.ts +42 -0
  11. package/dist/host.d.ts.map +1 -1
  12. package/dist/host.js +487 -70
  13. package/dist/host.js.map +1 -1
  14. package/dist/index.d.ts +3 -3
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +2 -2
  17. package/dist/index.js.map +1 -1
  18. package/dist/page-scripts.d.ts +20 -0
  19. package/dist/page-scripts.d.ts.map +1 -1
  20. package/dist/page-scripts.js +110 -0
  21. package/dist/page-scripts.js.map +1 -1
  22. package/dist/reach.d.ts +66 -0
  23. package/dist/reach.d.ts.map +1 -0
  24. package/dist/reach.js +189 -0
  25. package/dist/reach.js.map +1 -0
  26. package/dist/settle.d.ts +40 -0
  27. package/dist/settle.d.ts.map +1 -0
  28. package/dist/settle.js +30 -0
  29. package/dist/settle.js.map +1 -0
  30. package/dist/snapshot.d.ts +80 -2
  31. package/dist/snapshot.d.ts.map +1 -1
  32. package/dist/snapshot.js +326 -20
  33. package/dist/snapshot.js.map +1 -1
  34. package/dist/windows-engine.d.ts +1 -1
  35. package/dist/windows-engine.d.ts.map +1 -1
  36. package/dist/windows-engine.js +3 -1
  37. package/dist/windows-engine.js.map +1 -1
  38. package/package.json +3 -2
  39. package/src/classifier.ts +44 -7
  40. package/src/errors.ts +32 -0
  41. package/src/host.ts +608 -89
  42. package/src/index.ts +4 -0
  43. package/src/page-scripts.ts +108 -0
  44. package/src/reach.ts +211 -0
  45. package/src/settle.ts +60 -0
  46. package/src/snapshot.ts +402 -20
  47. package/src/windows-engine.ts +4 -1
package/src/index.ts CHANGED
@@ -40,10 +40,12 @@ export type {
40
40
  } from './detect.js'
41
41
  export {
42
42
  BrowserHumanRequiredError,
43
+ BrowserNoEffectError,
43
44
  BrowserOriginMismatchError,
44
45
  BrowserOutcomeUnknownError,
45
46
  BrowserSiteDeniedError,
46
47
  BrowserStaleRefError,
48
+ BrowserTargetUnclearError,
47
49
  BrowserUnavailableError,
48
50
  ProfileBusyError,
49
51
  } from './errors.js'
@@ -61,11 +63,13 @@ export {
61
63
  isCaptchaFrame,
62
64
  isCredentialField,
63
65
  isSignInAddress,
66
+ signInNotice,
64
67
  } from './classifier.js'
65
68
  export type {
66
69
  BrowserFieldFacts,
67
70
  BrowserHumanClassifierOptions,
68
71
  BrowserPageSignals,
72
+ BrowserSignInDetection,
69
73
  } from './classifier.js'
70
74
  export {
71
75
  BROWSER_PROFILE_NAME,
@@ -152,3 +152,111 @@ export function invisibleBoxes(limit: number): InvisibleBoxes {
152
152
  if (document.body) walk(document.body, false)
153
153
  return { scrollX: window.scrollX, scrollY: window.scrollY, boxes: out }
154
154
  }
155
+
156
+ /**
157
+ * Start a clock of the last change to the page: a mutation observer that
158
+ * stamps every change to the document. Run on every new document (an init
159
+ * script) so a change made right after an action is not missed.
160
+ */
161
+ // Serialised; keep it self-contained.
162
+ export function installMutationClock(): void {
163
+ const w = window as unknown as { __namzuChangedAt?: number }
164
+ if (w.__namzuChangedAt !== undefined) return
165
+ w.__namzuChangedAt = performance.now()
166
+ try {
167
+ new MutationObserver(() => {
168
+ w.__namzuChangedAt = performance.now()
169
+ }).observe(document, {
170
+ subtree: true,
171
+ childList: true,
172
+ attributes: true,
173
+ characterData: true,
174
+ })
175
+ } catch {
176
+ // A document that cannot be observed counts as still.
177
+ }
178
+ }
179
+
180
+ /** Milliseconds since the page last changed; a large number when the clock was never started. */
181
+ // Serialised; keep it self-contained.
182
+ export function msSinceLastChange(): number {
183
+ const w = window as unknown as { __namzuChangedAt?: number }
184
+ return w.__namzuChangedAt === undefined ? 1e9 : performance.now() - w.__namzuChangedAt
185
+ }
186
+
187
+ /** Whether the page has anything to read yet: text, or a control. */
188
+ // Serialised; keep it self-contained.
189
+ export function hasVisibleContent(): boolean {
190
+ const body = document.body
191
+ if (!body) return false
192
+ if (body.innerText.trim().length > 0) return true
193
+ return body.querySelector('input, button, select, textarea, img, a[href]') !== null
194
+ }
195
+
196
+ /** What {@link valueFacts} returns. */
197
+ export interface ValueFacts {
198
+ readonly kind: 'select' | 'checkbox' | 'radio' | 'file' | 'text' | 'other'
199
+ readonly value?: string
200
+ readonly options?: readonly string[]
201
+ readonly selected?: readonly string[]
202
+ readonly state: readonly string[]
203
+ }
204
+
205
+ /** The current value and state of one element, read from the page itself. */
206
+ // Serialised; keep it self-contained.
207
+ export function valueFacts(el: Element): ValueFacts {
208
+ const tag = el.tagName.toLowerCase()
209
+ const input = el as HTMLInputElement
210
+ const type = tag === 'input' ? (input.type || 'text').toLowerCase() : ''
211
+ const state: string[] = []
212
+ const aria = (name: string): string | null => el.getAttribute(name)
213
+ if (aria('aria-expanded') === 'true') state.push('expanded')
214
+ if (aria('aria-pressed') === 'true') state.push('pressed')
215
+ if (aria('aria-invalid') === 'true') state.push('invalid')
216
+ if ((el as HTMLInputElement).disabled || aria('aria-disabled') === 'true') state.push('disabled')
217
+ if ((el as HTMLInputElement).readOnly || aria('aria-readonly') === 'true') state.push('readonly')
218
+ if ((el as HTMLInputElement).required || aria('aria-required') === 'true') state.push('required')
219
+ const clip = (text: string): string => {
220
+ const t = text.replace(/\s+/g, ' ').trim()
221
+ return t.length > 500 ? `${t.slice(0, 499)}…` : t
222
+ }
223
+ if (tag === 'select') {
224
+ const select = el as HTMLSelectElement
225
+ const labels = Array.from(select.options).map((o) => clip(o.label || o.text))
226
+ const chosen = Array.from(select.selectedOptions).map((o) => clip(o.label || o.text))
227
+ return {
228
+ kind: 'select',
229
+ ...(chosen.length > 0 ? { value: chosen.join(', ') } : {}),
230
+ options: labels.slice(0, 200),
231
+ selected: chosen,
232
+ state,
233
+ }
234
+ }
235
+ if (type === 'checkbox' || type === 'radio') {
236
+ if (input.checked) state.push('checked')
237
+ else if (input.indeterminate) state.push('mixed')
238
+ return { kind: type, state }
239
+ }
240
+ const role = aria('role') ?? ''
241
+ if (role === 'checkbox' || role === 'radio' || role === 'switch') {
242
+ const checked = aria('aria-checked')
243
+ if (checked === 'true') state.push('checked')
244
+ else if (checked === 'mixed') state.push('mixed')
245
+ return { kind: role === 'radio' ? 'radio' : 'checkbox', state }
246
+ }
247
+ if (type === 'file') {
248
+ const names = Array.from(input.files ?? []).map((f) => f.name)
249
+ return { kind: 'file', ...(names.length > 0 ? { value: names.join(', ') } : {}), state }
250
+ }
251
+ if (tag === 'input' || tag === 'textarea') {
252
+ return { kind: 'text', ...(input.value !== '' ? { value: clip(input.value) } : {}), state }
253
+ }
254
+ const now = aria('aria-valuenow')
255
+ if (now !== null) return { kind: 'other', value: clip(aria('aria-valuetext') ?? now), state }
256
+ if ((el as HTMLElement).isContentEditable) {
257
+ const text = clip((el as HTMLElement).innerText ?? '')
258
+ return { kind: 'text', ...(text ? { value: text } : {}), state }
259
+ }
260
+ const text = clip((el as HTMLElement).innerText ?? el.textContent ?? '')
261
+ return { kind: 'other', ...(text ? { value: text } : {}), state }
262
+ }
package/src/reach.ts ADDED
@@ -0,0 +1,211 @@
1
+ /**
2
+ * Reaching the right element: where a click or hover lands, how a role/name
3
+ * or text target is described, which keys may go to the page without a ref,
4
+ * and how a failed action is told apart by cause.
5
+ *
6
+ * The functions marked "serialised" run inside the page and must stay
7
+ * self-contained (see page-scripts.ts for the rules that apply to them).
8
+ */
9
+ import type { BrowserTargetCandidate } from '@namzu/sdk'
10
+
11
+ /** Keys `press` accepts without a ref. None of them enters a character except Enter and Space. */
12
+ export const NAMED_KEYS = [
13
+ 'Escape',
14
+ 'Enter',
15
+ 'Tab',
16
+ 'Shift+Tab',
17
+ 'PageDown',
18
+ 'PageUp',
19
+ 'Home',
20
+ 'End',
21
+ 'Space',
22
+ ] as const
23
+
24
+ export type NamedKey = (typeof NAMED_KEYS)[number]
25
+
26
+ /** The canonical spelling of an accepted key, or undefined for any other. */
27
+ export function namedKey(raw: string): NamedKey | undefined {
28
+ const wanted = raw.trim().toLowerCase()
29
+ return NAMED_KEYS.find((key) => key.toLowerCase() === wanted)
30
+ }
31
+
32
+ /** Keys that put a character in a field or submit a form, so the focus must be known to be safe. */
33
+ export function keyCanCommit(key: NamedKey): boolean {
34
+ return key === 'Enter' || key === 'Space'
35
+ }
36
+
37
+ /** How long between key presses when `type` sends real key events. */
38
+ export const KEY_DELAY_MS = 20
39
+
40
+ /** Most candidates a refusal lists. */
41
+ export const CANDIDATES_MAX = 8
42
+
43
+ /** Where inside the element to aim, or the sign to use the middle. */
44
+ export type Aim =
45
+ | { readonly kind: 'centre' }
46
+ | { readonly kind: 'descendant'; readonly path: string }
47
+ | { readonly kind: 'text'; readonly x: number; readonly y: number }
48
+
49
+ /**
50
+ * Where to land on an element that is a container rather than a control:
51
+ * its first visible control, else the box of its own first text, else the
52
+ * middle. An element that is itself a control, or looks clickable, keeps the
53
+ * middle. `path` is an XPath relative to the element.
54
+ *
55
+ * Serialised; keep it self-contained.
56
+ */
57
+ export function aimInside(el: Element): Aim {
58
+ const controls =
59
+ 'a[href],button,input:not([type=hidden]),select,textarea,summary,label,[role=button],[role=link],[role=menuitem],[role=menuitemcheckbox],[role=menuitemradio],[role=tab],[role=option],[role=checkbox],[role=radio],[role=switch],[role=combobox],[role=textbox],[role=searchbox],[role=slider],[role=treeitem],[contenteditable=""],[contenteditable=true],[tabindex]:not([tabindex^="-"])'
60
+ const shown = (node: Element): boolean => {
61
+ const rect = node.getBoundingClientRect()
62
+ if (rect.width < 1 || rect.height < 1) return false
63
+ const style = getComputedStyle(node)
64
+ return style.visibility !== 'hidden' && style.display !== 'none'
65
+ }
66
+ if (
67
+ el.matches(controls) ||
68
+ el.hasAttribute('onclick') ||
69
+ getComputedStyle(el).cursor === 'pointer'
70
+ ) {
71
+ return { kind: 'centre' }
72
+ }
73
+ const inner = Array.from(el.querySelectorAll(controls)).find(shown)
74
+ if (inner) {
75
+ const steps: number[] = []
76
+ let node: Element | null = inner
77
+ while (node && node !== el) {
78
+ const parent: Element | null = node.parentElement
79
+ if (!parent) return { kind: 'centre' }
80
+ steps.unshift(Array.prototype.indexOf.call(parent.children, node) + 1)
81
+ node = parent
82
+ }
83
+ return { kind: 'descendant', path: `./${steps.map((i) => `*[${i}]`).join('/')}` }
84
+ }
85
+ const box = el.getBoundingClientRect()
86
+ const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT)
87
+ for (let node = walker.nextNode(); node; node = walker.nextNode()) {
88
+ const parent = node.parentElement
89
+ if (!parent || !(node.textContent ?? '').trim() || !shown(parent)) continue
90
+ if (/^(script|style|noscript|template)$/i.test(parent.tagName)) continue
91
+ const range = document.createRange()
92
+ range.selectNodeContents(node)
93
+ const rect = Array.from(range.getClientRects()).find((r) => r.width >= 1 && r.height >= 1)
94
+ if (!rect) continue
95
+ if (box.width <= rect.width * 1.5 + 8 && box.height <= rect.height * 1.5 + 8) {
96
+ return { kind: 'centre' }
97
+ }
98
+ return {
99
+ kind: 'text',
100
+ x: rect.left + rect.width / 2 - (box.left + el.clientLeft),
101
+ y: rect.top + rect.height / 2 - (box.top + el.clientTop),
102
+ }
103
+ }
104
+ return { kind: 'centre' }
105
+ }
106
+
107
+ /**
108
+ * The deepest focused element, through open shadow roots and same-origin
109
+ * frames, or null when nothing but the page is focused.
110
+ *
111
+ * Serialised; keep it self-contained.
112
+ */
113
+ export function deepFocus(): Element | null {
114
+ let active: Element | null = document.activeElement
115
+ for (let depth = 0; active && depth < 20; depth++) {
116
+ if (active.shadowRoot?.activeElement) {
117
+ active = active.shadowRoot.activeElement
118
+ continue
119
+ }
120
+ const frame = active as HTMLIFrameElement
121
+ const inner = frame.tagName === 'IFRAME' ? frame.contentDocument?.activeElement : null
122
+ if (inner) {
123
+ active = inner
124
+ continue
125
+ }
126
+ break
127
+ }
128
+ return !active || active === document.body || active === document.documentElement ? null : active
129
+ }
130
+
131
+ /**
132
+ * Whether the focused element is one whose inside cannot be read: a shadow
133
+ * host. A plain element only holds the focus when it is a control, a frame,
134
+ * editable, or given a tab stop; any other element holding it is a host whose
135
+ * root is closed (an open root is followed by {@link deepFocus}). Serialised.
136
+ */
137
+ export function focusIsOpaque(el: Element): boolean {
138
+ return !el.matches(
139
+ 'input,textarea,select,button,a[href],area[href],summary,iframe,object,embed,[contenteditable]:not([contenteditable=false]),[tabindex]',
140
+ )
141
+ }
142
+
143
+ /** What a candidate looks like to a person: its role and its name. Serialised. */
144
+ export function describeCandidate(el: Element): BrowserTargetCandidate {
145
+ const tag = el.tagName.toLowerCase()
146
+ const input = el as HTMLInputElement
147
+ const implicit: Record<string, string> = {
148
+ a: 'link',
149
+ button: 'button',
150
+ select: 'combobox',
151
+ textarea: 'textbox',
152
+ summary: 'button',
153
+ li: 'listitem',
154
+ img: 'image',
155
+ nav: 'navigation',
156
+ table: 'table',
157
+ h1: 'heading',
158
+ h2: 'heading',
159
+ h3: 'heading',
160
+ h4: 'heading',
161
+ h5: 'heading',
162
+ h6: 'heading',
163
+ }
164
+ let role = el.getAttribute('role') ?? implicit[tag] ?? tag
165
+ if (tag === 'input') {
166
+ const type = (input.type || 'text').toLowerCase()
167
+ role = ['checkbox', 'radio'].includes(type)
168
+ ? type
169
+ : ['button', 'submit', 'reset', 'image'].includes(type)
170
+ ? 'button'
171
+ : 'textbox'
172
+ }
173
+ const raw =
174
+ el.getAttribute('aria-label') ||
175
+ (el as HTMLElement).innerText ||
176
+ el.textContent ||
177
+ input.value ||
178
+ el.getAttribute('title') ||
179
+ el.getAttribute('placeholder') ||
180
+ ''
181
+ return { role, name: raw.replace(/\s+/g, ' ').trim().slice(0, 80) }
182
+ }
183
+
184
+ /** Why an action that stopped before touching the page stopped, in a clause. */
185
+ export function noEffectReason(error: unknown): string {
186
+ const text = error instanceof Error ? error.message : String(error)
187
+ if (/intercepts pointer events/i.test(text)) return 'another element is covering it'
188
+ if (/not visible/i.test(text)) return 'it is not visible'
189
+ if (/not enabled/i.test(text)) return 'it is disabled'
190
+ if (/not stable/i.test(text)) return 'it kept moving'
191
+ if (/not attached|detached/i.test(text)) return 'it left the page'
192
+ if (/outside of the viewport/i.test(text))
193
+ return 'it is outside the visible area and could not be scrolled in'
194
+ if (/timeout/i.test(text)) return 'it did not become ready to act on in time'
195
+ return (text.split('\n')[0] ?? '').slice(0, 160)
196
+ }
197
+
198
+ /**
199
+ * Did a failed action stop before it did anything? Playwright logs
200
+ * "performing <action> action" the moment it sends input, so a timeout whose
201
+ * log never reaches that line left the page alone. Anything else — including
202
+ * an error that carries no log — may have changed the page.
203
+ */
204
+ export function failedBeforeActing(error: unknown): boolean {
205
+ if (!(error instanceof Error)) return false
206
+ const text = error.message
207
+ if (error.name !== 'TimeoutError' && !/Timeout \d+ms exceeded/.test(text)) return false
208
+ return !/performing \w+ action|action done|scheduled navigations|\.(?:type|pressSequentially|fill)\(/i.test(
209
+ text,
210
+ )
211
+ }
package/src/settle.ts ADDED
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Waiting for a page to go quiet, as a small state machine over an injected
3
+ * clock and probe so that its timing can be tested without waiting.
4
+ *
5
+ * A page is quiet when nothing in it has changed and no request is in flight
6
+ * for `quietMs`. The wait is capped: a page that animates or polls forever is
7
+ * never quiet, and the caller reports that instead of waiting on it.
8
+ */
9
+
10
+ /** Time, as the host or a test supplies it. */
11
+ export interface SettleClock {
12
+ now(): number
13
+ sleep(ms: number): Promise<void>
14
+ }
15
+
16
+ /** How long the page has been still, in milliseconds; 0 while a request is in flight. */
17
+ export interface SettleProbe {
18
+ stillForMs(): Promise<number>
19
+ }
20
+
21
+ export interface SettleOptions {
22
+ /** How long the page must be still. */
23
+ readonly quietMs: number
24
+ /** The longest the whole wait may take. */
25
+ readonly capMs: number
26
+ /** How often the probe is read. Default: a fifth of `quietMs`, at least 20. */
27
+ readonly pollMs?: number
28
+ }
29
+
30
+ export interface SettleOutcome {
31
+ /** The page went quiet before the cap. */
32
+ readonly quiet: boolean
33
+ /** How long the wait took. */
34
+ readonly waitedMs: number
35
+ readonly capMs: number
36
+ }
37
+
38
+ /**
39
+ * Wait until `probe` has reported `quietMs` of stillness, or `capMs` has
40
+ * passed. The stillness is never counted from before the wait began, so an
41
+ * event that is still on its way to the host (a popup, a request the browser
42
+ * has not announced yet) has `quietMs` to arrive.
43
+ */
44
+ export async function waitUntilQuiet(
45
+ clock: SettleClock,
46
+ probe: SettleProbe,
47
+ options: SettleOptions,
48
+ ): Promise<SettleOutcome> {
49
+ const { quietMs, capMs } = options
50
+ const poll = Math.max(20, options.pollMs ?? Math.floor(quietMs / 5))
51
+ const start = clock.now()
52
+ for (;;) {
53
+ const elapsed = clock.now() - start
54
+ const still = Math.min(await probe.stillForMs(), clock.now() - start)
55
+ if (still >= quietMs) return { quiet: true, waitedMs: clock.now() - start, capMs }
56
+ if (elapsed >= capMs) return { quiet: false, waitedMs: clock.now() - start, capMs }
57
+ const remainingToQuiet = Math.max(1, quietMs - still)
58
+ await clock.sleep(Math.min(poll, remainingToQuiet, Math.max(1, capMs - elapsed)))
59
+ }
60
+ }