@namzu/browser 2.0.1 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -0
- package/dist/classifier.d.ts +22 -1
- package/dist/classifier.d.ts.map +1 -1
- package/dist/classifier.js +30 -7
- package/dist/classifier.js.map +1 -1
- package/dist/errors.d.ts +19 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +26 -0
- package/dist/errors.js.map +1 -1
- package/dist/host.d.ts +42 -0
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +483 -69
- package/dist/host.js.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/page-scripts.d.ts +20 -0
- package/dist/page-scripts.d.ts.map +1 -1
- package/dist/page-scripts.js +110 -0
- package/dist/page-scripts.js.map +1 -1
- package/dist/reach.d.ts +66 -0
- package/dist/reach.d.ts.map +1 -0
- package/dist/reach.js +189 -0
- package/dist/reach.js.map +1 -0
- package/dist/settle.d.ts +40 -0
- package/dist/settle.d.ts.map +1 -0
- package/dist/settle.js +30 -0
- package/dist/settle.js.map +1 -0
- package/dist/snapshot.d.ts +80 -2
- package/dist/snapshot.d.ts.map +1 -1
- package/dist/snapshot.js +326 -20
- package/dist/snapshot.js.map +1 -1
- package/package.json +3 -2
- package/src/classifier.ts +44 -7
- package/src/errors.ts +32 -0
- package/src/host.ts +606 -83
- package/src/index.ts +4 -0
- package/src/page-scripts.ts +108 -0
- package/src/reach.ts +211 -0
- package/src/settle.ts +60 -0
- package/src/snapshot.ts +402 -20
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,
|
package/src/page-scripts.ts
CHANGED
|
@@ -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
|
+
}
|