autokast 0.0.0 → 0.1.1

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 (79) hide show
  1. package/LICENSE +29 -0
  2. package/README.md +165 -0
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +300 -0
  5. package/dist/index.d.ts +4 -0
  6. package/dist/index.js +4 -0
  7. package/dist/inspect.d.ts +26 -0
  8. package/dist/inspect.js +193 -0
  9. package/dist/record/animations.d.ts +7 -0
  10. package/dist/record/animations.js +34 -0
  11. package/dist/record/capture.d.ts +85 -0
  12. package/dist/record/capture.js +202 -0
  13. package/dist/record/cast.d.ts +142 -0
  14. package/dist/record/cast.js +680 -0
  15. package/dist/record/cursor-style.d.ts +33 -0
  16. package/dist/record/cursor-style.js +252 -0
  17. package/dist/record/defaults.d.ts +96 -0
  18. package/dist/record/defaults.js +125 -0
  19. package/dist/record/editor.d.ts +11 -0
  20. package/dist/record/editor.js +48 -0
  21. package/dist/record/frame-pump.d.ts +91 -0
  22. package/dist/record/frame-pump.js +306 -0
  23. package/dist/record/index.d.ts +11 -0
  24. package/dist/record/index.js +287 -0
  25. package/dist/record/motion.d.ts +48 -0
  26. package/dist/record/motion.js +112 -0
  27. package/dist/record/pace.d.ts +69 -0
  28. package/dist/record/pace.js +133 -0
  29. package/dist/record/random.d.ts +12 -0
  30. package/dist/record/random.js +24 -0
  31. package/dist/record/scroll.d.ts +71 -0
  32. package/dist/record/scroll.js +249 -0
  33. package/dist/record/timeline.d.ts +34 -0
  34. package/dist/record/timeline.js +44 -0
  35. package/dist/render/background.d.ts +12 -0
  36. package/dist/render/background.js +209 -0
  37. package/dist/render/browser.d.ts +46 -0
  38. package/dist/render/browser.js +223 -0
  39. package/dist/render/camera.d.ts +119 -0
  40. package/dist/render/camera.js +372 -0
  41. package/dist/render/captions.d.ts +114 -0
  42. package/dist/render/captions.js +254 -0
  43. package/dist/render/color.d.ts +23 -0
  44. package/dist/render/color.js +78 -0
  45. package/dist/render/compositor.d.ts +185 -0
  46. package/dist/render/compositor.js +656 -0
  47. package/dist/render/cursor.d.ts +85 -0
  48. package/dist/render/cursor.js +314 -0
  49. package/dist/render/cursors/shapes.d.ts +34 -0
  50. package/dist/render/cursors/shapes.js +268 -0
  51. package/dist/render/defaults.d.ts +91 -0
  52. package/dist/render/defaults.js +139 -0
  53. package/dist/render/easing.d.ts +13 -0
  54. package/dist/render/easing.js +40 -0
  55. package/dist/render/effects.d.ts +39 -0
  56. package/dist/render/effects.js +91 -0
  57. package/dist/render/encoder.d.ts +52 -0
  58. package/dist/render/encoder.js +226 -0
  59. package/dist/render/index.d.ts +19 -0
  60. package/dist/render/index.js +138 -0
  61. package/dist/render/keycaps.d.ts +67 -0
  62. package/dist/render/keycaps.js +270 -0
  63. package/dist/render/scene.d.ts +59 -0
  64. package/dist/render/scene.js +230 -0
  65. package/dist/render/source.d.ts +21 -0
  66. package/dist/render/source.js +57 -0
  67. package/dist/render/spring.d.ts +11 -0
  68. package/dist/render/spring.js +47 -0
  69. package/dist/render/stage.d.ts +59 -0
  70. package/dist/render/stage.js +91 -0
  71. package/dist/render/timeline.d.ts +70 -0
  72. package/dist/render/timeline.js +157 -0
  73. package/dist/session.d.ts +14 -0
  74. package/dist/session.js +33 -0
  75. package/dist/types.d.ts +708 -0
  76. package/dist/types.js +1 -0
  77. package/package.json +61 -3
  78. package/skills/autokast/SKILL.md +300 -0
  79. package/skills/autokast/reference/jupyterlab.md +100 -0
@@ -0,0 +1,680 @@
1
+ import { CAST_DEFAULTS } from "./defaults.js";
2
+ import { caretLinePrefix, leadingWhitespace } from "./editor.js";
3
+ import { cursorPath, dragEase, easeInOutCubic, moveDuration, moveEase, scrollDuration, typingDelay, } from "./motion.js";
4
+ import { createRandom } from "./random.js";
5
+ import { hitCheck, planScroll, scrollIdle } from "./scroll.js";
6
+ const MOVE_TICK = 8;
7
+ const SCROLL_TICK = 16;
8
+ const STABLE_INTERVAL = 20;
9
+ const MAX_SCROLL_STEPS = 8;
10
+ function isPoint(target) {
11
+ return (typeof target === 'object' &&
12
+ target !== null &&
13
+ typeof target.x === 'number' &&
14
+ typeof target.y === 'number');
15
+ }
16
+ function isRect(target) {
17
+ return typeof target.width === 'number' && typeof target.height === 'number';
18
+ }
19
+ /**
20
+ * True when a position (fractions of the target size) is outside the target.
21
+ */
22
+ function isOutside(position) {
23
+ return !!position && (position.x < 0 || position.x > 1 || position.y < 0 || position.y > 1);
24
+ }
25
+ function sameBox(a, b) {
26
+ return (Math.abs(a.x - b.x) < 0.5 &&
27
+ Math.abs(a.y - b.y) < 0.5 &&
28
+ Math.abs(a.width - b.width) < 0.5 &&
29
+ Math.abs(a.height - b.height) < 0.5);
30
+ }
31
+ function intersect(a, b) {
32
+ const x = Math.max(a.x, b.x);
33
+ const y = Math.max(a.y, b.y);
34
+ const right = Math.min(a.x + a.width, b.x + b.width);
35
+ const bottom = Math.min(a.y + a.height, b.y + b.height);
36
+ return right > x && bottom > y ? { x, y, width: right - x, height: bottom - y } : undefined;
37
+ }
38
+ function withoutUndefined(value) {
39
+ return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
40
+ }
41
+ /**
42
+ * How long a zoom call blocks: the whole camera move for `wait: true`, none for `false`,
43
+ * else the given milliseconds or, by default, the first part of the move.
44
+ */
45
+ function zoomWait(options) {
46
+ const duration = options.duration ?? CAST_DEFAULTS.zoomDuration;
47
+ if (typeof options.wait === 'number') {
48
+ return options.wait;
49
+ }
50
+ if (options.wait !== undefined) {
51
+ return options.wait ? duration : 0;
52
+ }
53
+ return Math.min(duration * CAST_DEFAULTS.zoomWaitPart, CAST_DEFAULTS.zoomWaitMax);
54
+ }
55
+ function shorten(text, max) {
56
+ return text.length > max ? `${text.slice(0, max - 1)}…` : text;
57
+ }
58
+ /**
59
+ * Short description of a target, for error messages and the action log.
60
+ */
61
+ export function describeTarget(target) {
62
+ if (typeof target === 'string') {
63
+ return JSON.stringify(shorten(target, 60));
64
+ }
65
+ if (isPoint(target)) {
66
+ const { x, y } = target;
67
+ return JSON.stringify(isRect(target) ? { x, y, width: target.width, height: target.height } : { x, y });
68
+ }
69
+ return shorten(String(target), 60);
70
+ }
71
+ function describeText(text) {
72
+ return JSON.stringify(shorten(text, 30));
73
+ }
74
+ /**
75
+ * The Cast implementation: drives the page with human-like input and logs the timeline.
76
+ */
77
+ export class Director {
78
+ page;
79
+ viewport;
80
+ /**
81
+ * The last Cast call that succeeded, for error messages.
82
+ */
83
+ lastCall;
84
+ options;
85
+ timeline;
86
+ pace;
87
+ /**
88
+ * Default time limit for Playwright waits, which run in real time.
89
+ */
90
+ timeout;
91
+ cursorStyle;
92
+ motionRandom;
93
+ typingRandom;
94
+ failures = new WeakMap();
95
+ position;
96
+ region;
97
+ constructor(context) {
98
+ this.page = context.page;
99
+ this.options = context.options;
100
+ this.timeline = context.timeline;
101
+ this.pace = context.pace;
102
+ this.timeout = context.options.timeout * context.pace.timeoutScale;
103
+ this.cursorStyle = context.cursorStyle;
104
+ this.viewport = { ...context.options.viewport };
105
+ this.position = { ...context.options.cursor.start };
106
+ this.motionRandom = createRandom(context.options.seed);
107
+ this.typingRandom = createRandom(context.options.seed ^ 0x9e3779b9);
108
+ }
109
+ /**
110
+ * The innermost Cast call that threw `error`, if a Cast call threw it.
111
+ */
112
+ failureOf(error) {
113
+ return typeof error === 'object' && error !== null ? this.failures.get(error) : undefined;
114
+ }
115
+ moveTo(target, options = {}) {
116
+ return this.step(`moveTo(${describeTarget(target)})`, async () => {
117
+ const { point } = await this.resolve(target, options);
118
+ await this.moveCursor(point, options.duration);
119
+ });
120
+ }
121
+ click(target, options = {}) {
122
+ return this.step(`click(${describeTarget(target)})`, () => this.clickTarget(target, options));
123
+ }
124
+ dblclick(target, options = {}) {
125
+ return this.step(`dblclick(${describeTarget(target)})`, () => this.clickTarget(target, { ...options, clickCount: 2 }));
126
+ }
127
+ rightClick(target, options = {}) {
128
+ return this.step(`rightClick(${describeTarget(target)})`, () => this.clickTarget(target, { ...options, button: 'right' }));
129
+ }
130
+ hover(target, options = {}) {
131
+ return this.step(`hover(${describeTarget(target)})`, async () => {
132
+ const { point } = await this.resolve(target, options);
133
+ await this.moveCursor(point, options.duration);
134
+ await this.pace.sleep(options.hold ?? CAST_DEFAULTS.hoverHold);
135
+ });
136
+ }
137
+ drag(from, to, options = {}) {
138
+ return this.step(`drag(${describeTarget(from)}, ${describeTarget(to)})`, async () => {
139
+ const source = await this.resolve(from, options);
140
+ await this.moveCursor(source.point, options.duration);
141
+ await this.pace.sleep(this.options.pacing.beforeClick);
142
+ await this.mouseDown('left', 1);
143
+ try {
144
+ await this.pace.sleep(CAST_DEFAULTS.dragHold);
145
+ const destination = await this.resolve(to, { ...options, position: options.toPosition });
146
+ const distance = Math.hypot(destination.point.x - this.position.x, destination.point.y - this.position.y);
147
+ const duration = options.dragDuration ??
148
+ Math.max(CAST_DEFAULTS.dragMinDuration, CAST_DEFAULTS.dragSlowdown * moveDuration(distance, this.options.cursor));
149
+ const curvature = this.options.cursor.curvature / 2;
150
+ await this.moveCursor(destination.point, duration, curvature, dragEase);
151
+ await this.pace.sleep(CAST_DEFAULTS.dragHold);
152
+ }
153
+ finally {
154
+ await this.mouseUp('left', 1);
155
+ }
156
+ await this.pace.sleep(this.options.pacing.afterClick);
157
+ });
158
+ }
159
+ select(target, values, options = {}) {
160
+ return this.step(`select(${describeTarget(target)}, ${JSON.stringify(values)})`, async () => {
161
+ await this.clickTarget(target, { ...options, afterClick: 0 });
162
+ await this.locatorOf(target).selectOption(values, {
163
+ timeout: options.timeout ?? this.timeout,
164
+ });
165
+ await this.pace.sleep(options.afterClick ?? this.options.pacing.afterClick);
166
+ });
167
+ }
168
+ scroll(delta, options = {}) {
169
+ return this.step(`scroll(${JSON.stringify(delta)})`, async () => {
170
+ if (options.at !== undefined) {
171
+ const { point } = await this.resolve(options.at);
172
+ await this.moveCursor(point);
173
+ }
174
+ const dx = delta.x ?? 0;
175
+ const dy = delta.y ?? 0;
176
+ const distance = Math.hypot(dx, dy);
177
+ if (distance === 0) {
178
+ return;
179
+ }
180
+ await this.wheel(dx, dy, options.duration ?? scrollDuration(distance));
181
+ });
182
+ }
183
+ scrollTo(target, options = {}) {
184
+ return this.step(`scrollTo(${describeTarget(target)})`, async () => {
185
+ const timeout = options.timeout ?? this.timeout;
186
+ const block = options.block ?? 'center';
187
+ if (isPoint(target)) {
188
+ const rect = isRect(target) ? target : { ...target, width: 0, height: 0 };
189
+ const plan = await this.page
190
+ .locator(':root')
191
+ .evaluate(planScroll, { block, ifNeeded: false, cursor: this.position, rect });
192
+ if (plan.point && (plan.dx || plan.dy)) {
193
+ await this.moveCursor(plan.point);
194
+ await this.wheel(plan.dx, plan.dy, options.duration ?? scrollDuration(Math.hypot(plan.dx, plan.dy)));
195
+ }
196
+ return;
197
+ }
198
+ const locator = this.locatorOf(target);
199
+ await locator.waitFor({ state: 'visible', timeout });
200
+ await this.bringIntoView(locator, {
201
+ block,
202
+ ifNeeded: block === 'nearest',
203
+ duration: options.duration,
204
+ timeout,
205
+ smooth: true,
206
+ });
207
+ });
208
+ }
209
+ type(text, options = {}) {
210
+ return this.step(`type(${describeText(text)})`, async () => {
211
+ if (options.into !== undefined) {
212
+ await this.clickTarget(options.into, { position: options.position });
213
+ }
214
+ const delay = options.delay ?? this.options.typing.delay;
215
+ const variance = options.variance ?? this.options.typing.variance;
216
+ const chars = [...text.replace(/\r\n?/g, '\n')];
217
+ const auto = (options.indent ?? 'auto') === 'auto';
218
+ let due = this.timeline.now();
219
+ let previous = '';
220
+ for (let i = 0; i < chars.length; i++) {
221
+ const char = chars[i];
222
+ if (previous) {
223
+ due += typingDelay(previous, delay, variance, this.typingRandom);
224
+ await this.pace.sleep(due - this.timeline.now());
225
+ }
226
+ const t = await this.pace.input(() => char === '\n' ? this.page.keyboard.press('Enter') : this.page.keyboard.type(char));
227
+ this.timeline.push({ type: 'key', t, kind: 'text', key: char });
228
+ previous = char;
229
+ if (auto && char === '\n') {
230
+ const next = chars
231
+ .slice(i + 1)
232
+ .join('')
233
+ .split('\n')[0];
234
+ const present = await this.alignIndent(leadingWhitespace(next), delay, variance);
235
+ i += present;
236
+ previous = present > 0 ? chars[i] : previous;
237
+ }
238
+ // After a slow dispatch, keep the rhythm instead of rushing to catch up.
239
+ due = Math.max(due, this.timeline.now());
240
+ }
241
+ await this.pace.sleep(this.options.pacing.afterType);
242
+ });
243
+ }
244
+ press(keys, options = {}) {
245
+ return this.step(`press(${JSON.stringify(keys)})`, async () => {
246
+ const t = await this.pace.input(() => this.page.keyboard.press(keys, { delay: options.hold }));
247
+ this.timeline.push({ type: 'key', t, kind: 'shortcut', key: keys });
248
+ await this.pace.sleep(this.options.pacing.afterType);
249
+ });
250
+ }
251
+ zoomTo(target, options = {}) {
252
+ return this.step(`zoomTo(${describeTarget(target)})`, async () => {
253
+ const focus = await this.resolveRect(target);
254
+ const { scale, level, padding, duration, easing, follow } = options;
255
+ const t = this.timeline.now();
256
+ this.push({ type: 'zoom', t, focus, scale, level, padding, duration, easing, follow });
257
+ await this.pace.sleep(zoomWait(options));
258
+ });
259
+ }
260
+ zoom(level, options = {}) {
261
+ return this.step(`zoom(${JSON.stringify(level)})`, async () => {
262
+ if (typeof level === 'number' && !(level > 0 && Number.isFinite(level))) {
263
+ throw new Error(`cast.zoom(level) needs a level name or a scale above 0, got ${level}.`);
264
+ }
265
+ const { x, y } = this.position;
266
+ const { duration, easing } = options;
267
+ this.push({
268
+ type: 'zoom',
269
+ t: this.timeline.now(),
270
+ focus: { x, y, width: 0, height: 0 },
271
+ ...(typeof level === 'number' ? { scale: level } : { level }),
272
+ duration,
273
+ easing,
274
+ follow: options.follow ?? 'cursor',
275
+ anchor: 'cursor',
276
+ });
277
+ await this.pace.sleep(zoomWait(options));
278
+ });
279
+ }
280
+ zoomOut(options = {}) {
281
+ return this.step('zoomOut()', async () => {
282
+ const { duration, easing } = options;
283
+ this.push({ type: 'zoom', t: this.timeline.now(), focus: null, duration, easing });
284
+ await this.pace.sleep(zoomWait(options));
285
+ });
286
+ }
287
+ wait(ms) {
288
+ return this.step(`wait(${ms})`, async () => {
289
+ if (!Number.isFinite(ms) || ms < 0) {
290
+ throw new Error(`cast.wait(ms) needs a number of milliseconds of 0 or more, got ${ms}.`);
291
+ }
292
+ await this.pace.sleep(ms);
293
+ });
294
+ }
295
+ cut(fn) {
296
+ return this.step('cut()', () => this.inRegion('cut', fn, (t, end) => this.push({ type: 'cut', t, end })));
297
+ }
298
+ speed(rate, fn) {
299
+ return this.step(`speed(${rate})`, async () => {
300
+ if (!Number.isFinite(rate) || rate <= 0) {
301
+ throw new Error(`cast.speed(rate, fn) needs a rate above 0 (4 plays 4x faster), got ${rate}.`);
302
+ }
303
+ return this.inRegion('speed', fn, (t, end) => this.push({ type: 'speed', t, end, rate }));
304
+ });
305
+ }
306
+ get browserFrame() {
307
+ return this.options.render?.frame?.chrome === 'browser';
308
+ }
309
+ showUrl(options = {}) {
310
+ return this.step('showUrl()', async () => {
311
+ if (!this.browserFrame)
312
+ return;
313
+ const show = options.duration ?? CAST_DEFAULTS.addressShow;
314
+ this.push({ type: 'url', t: this.timeline.now(), url: this.page.url(), show });
315
+ if (options.wait ?? true) {
316
+ await this.pace.sleep(show);
317
+ }
318
+ });
319
+ }
320
+ goto(url, options = {}) {
321
+ return this.step(`goto(${describeText(url)})`, async () => {
322
+ const target = new URL(url, this.page.url()).href;
323
+ const open = () => this.page.goto(target);
324
+ if (this.region === 'cut') {
325
+ await open();
326
+ return;
327
+ }
328
+ if (options.typing ?? this.browserFrame) {
329
+ const text = target.replace(/^https?:\/\//, '');
330
+ const typing = Math.min(CAST_DEFAULTS.addressMax, CAST_DEFAULTS.addressPerChar * text.length);
331
+ this.push({ type: 'url', t: this.timeline.now(), url: target, typing });
332
+ await this.pace.sleep(typing + CAST_DEFAULTS.addressEnter);
333
+ }
334
+ await this.inRegion('cut', open, (t, end) => this.push({ type: 'cut', t, end }));
335
+ });
336
+ }
337
+ caption(text, options = {}) {
338
+ return this.step(`caption(${describeText(text)})`, async () => {
339
+ const duration = options.duration ?? CAST_DEFAULTS.captionBase + CAST_DEFAULTS.captionPerChar * text.length;
340
+ this.push({ type: 'caption', t: this.timeline.now(), duration, text });
341
+ if (options.wait) {
342
+ await this.pace.sleep(duration);
343
+ }
344
+ });
345
+ }
346
+ spotlight(target, options = {}) {
347
+ return this.step(`spotlight(${describeTarget(target)})`, async () => {
348
+ const rect = await this.resolveRect(target);
349
+ const duration = options.duration ?? CAST_DEFAULTS.spotlightDuration;
350
+ const { padding, radius } = options;
351
+ this.push({ type: 'spotlight', t: this.timeline.now(), duration, rect, padding, radius });
352
+ if (options.wait) {
353
+ await this.pace.sleep(duration);
354
+ }
355
+ });
356
+ }
357
+ marker(label) {
358
+ const t = this.timeline.now();
359
+ this.push({ type: 'marker', t, label: String(label) });
360
+ this.push({ type: 'action', t, end: t, call: `marker(${describeText(String(label))})` });
361
+ }
362
+ /**
363
+ * Runs one Cast call. Remembers the innermost failing call for the error message.
364
+ */
365
+ async step(call, action) {
366
+ const t = this.timeline.now();
367
+ try {
368
+ const result = await action();
369
+ this.lastCall = `cast.${call}`;
370
+ return result;
371
+ }
372
+ catch (error) {
373
+ if (typeof error === 'object' && error !== null && !this.failures.has(error)) {
374
+ this.failures.set(error, { call: `cast.${call}`, t: this.timeline.now() });
375
+ }
376
+ throw error;
377
+ }
378
+ finally {
379
+ this.timeline.push({ type: 'action', t, end: this.timeline.now(), call });
380
+ }
381
+ }
382
+ push(event) {
383
+ this.timeline.push(withoutUndefined(event));
384
+ }
385
+ async inRegion(kind, fn, done) {
386
+ if (this.region) {
387
+ throw new Error(`cast.${kind}() cannot run inside cast.${this.region}(): cut and speed regions do not nest. ` +
388
+ `Move the cast.${kind}() call out of the cast.${this.region}() callback.`);
389
+ }
390
+ this.region = kind;
391
+ const t = this.timeline.now();
392
+ if (kind === 'cut') {
393
+ await this.pace.capture(false);
394
+ }
395
+ try {
396
+ return await fn();
397
+ }
398
+ finally {
399
+ const end = kind === 'cut' ? await this.pace.capture(true) : this.timeline.now();
400
+ this.region = undefined;
401
+ done(t, end);
402
+ }
403
+ }
404
+ locatorOf(target) {
405
+ return typeof target === 'string' ? this.page.locator(target) : target;
406
+ }
407
+ async resolve(target, options = {}) {
408
+ if (isPoint(target)) {
409
+ if (!isRect(target)) {
410
+ return { point: { x: target.x, y: target.y } };
411
+ }
412
+ return { point: this.pointIn(target, options.position), box: target };
413
+ }
414
+ const locator = this.locatorOf(target);
415
+ const box = await this.stableBox(locator, options.timeout);
416
+ return { point: this.pointIn(box, options.position), box, locator };
417
+ }
418
+ async resolveRect(target) {
419
+ if (isPoint(target)) {
420
+ const { x, y } = target;
421
+ return isRect(target)
422
+ ? { x, y, width: target.width, height: target.height }
423
+ : { x, y, width: 0, height: 0 };
424
+ }
425
+ return this.stableBox(this.locatorOf(target));
426
+ }
427
+ /**
428
+ * A point inside `box`: at `position` (fractions of the size), or near the center of the
429
+ * visible part with a small random offset.
430
+ */
431
+ pointIn(box, position) {
432
+ if (position) {
433
+ return { x: box.x + box.width * position.x, y: box.y + box.height * position.y };
434
+ }
435
+ const area = intersect(box, { x: 0, y: 0, ...this.viewport }) ?? box;
436
+ const jitterX = Math.min(area.width * 0.15, 8);
437
+ const jitterY = Math.min(area.height * 0.15, 4);
438
+ return {
439
+ x: area.x + area.width / 2 + (this.motionRandom() * 2 - 1) * jitterX,
440
+ y: area.y + area.height / 2 + (this.motionRandom() * 2 - 1) * jitterY,
441
+ };
442
+ }
443
+ /**
444
+ * Waits until the element is visible, scrolls it into view, and returns its bounding box
445
+ * once two reads in a row give the same box.
446
+ */
447
+ async stableBox(locator, timeout = this.timeout) {
448
+ await locator.waitFor({ state: 'visible', timeout });
449
+ const plan = await this.bringIntoView(locator, {
450
+ block: 'center',
451
+ ifNeeded: true,
452
+ timeout,
453
+ smooth: this.options.scrollBehavior === 'smooth',
454
+ });
455
+ // Without an animation that can move it, the box from the scroll plan is final: no
456
+ // need to compare two boxes a frame apart.
457
+ if (plan && !plan.inFrame && !plan.moving) {
458
+ return plan.box;
459
+ }
460
+ // The time limit is for the page, so the scroll animation does not count.
461
+ const deadline = Date.now() + timeout;
462
+ const remaining = () => Math.max(1, deadline - Date.now());
463
+ let previous = await locator.boundingBox({ timeout: remaining() });
464
+ for (;;) {
465
+ await this.pace.sleep(STABLE_INTERVAL);
466
+ const box = await locator.boundingBox({ timeout: remaining() });
467
+ if (box && previous && sameBox(box, previous)) {
468
+ return box;
469
+ }
470
+ if (Date.now() > deadline) {
471
+ throw new Error(`${String(locator)} did not stop moving within ${timeout} ms ` +
472
+ `(last bounding box: ${JSON.stringify(box)}).`);
473
+ }
474
+ previous = box;
475
+ }
476
+ }
477
+ async clickTarget(target, options) {
478
+ const resolved = await this.resolve(target, options);
479
+ await this.moveCursor(resolved.point, options.duration);
480
+ let ready;
481
+ if (resolved.locator && resolved.box) {
482
+ // Outside the target, the click lands on whatever is at that point, like a real
483
+ // click: a check that the target receives it would always fail.
484
+ const check = !options.force && !isOutside(options.position);
485
+ // The check runs during the pause before the press, so that it adds no time.
486
+ ready = this.prepareClick(resolved.locator, resolved.box, check, options.timeout);
487
+ ready.catch(() => { });
488
+ }
489
+ await this.pace.sleep(this.options.pacing.beforeClick);
490
+ await ready;
491
+ await this.pressButton(options.button ?? 'left', options.clickCount ?? 1, options.modifiers);
492
+ await this.pace.sleep(options.afterClick ?? this.options.pacing.afterClick);
493
+ }
494
+ /**
495
+ * Before the press: moves the cursor again when the element moved after the cursor
496
+ * arrived, then makes sure that the click reaches it. One in-page check covers the usual
497
+ * case; Playwright's trial click, with its waits and error messages, runs only when that
498
+ * check fails, and for elements in a child frame.
499
+ */
500
+ async prepareClick(locator, box, check, timeout) {
501
+ const state = await locator.evaluate(hitCheck, this.position, {
502
+ timeout: timeout ?? this.timeout,
503
+ });
504
+ let current = box;
505
+ if (state.inFrame) {
506
+ current = await this.followTarget(locator, box, timeout);
507
+ }
508
+ else if (!sameBox(state.box, box)) {
509
+ current = await this.followTarget(locator, box, timeout, state.box);
510
+ }
511
+ else if (state.receives || !check) {
512
+ return;
513
+ }
514
+ if (check) {
515
+ await this.checkActionable(locator, current, timeout);
516
+ }
517
+ }
518
+ /**
519
+ * Moves the cursor again when the element moved after the cursor arrived.
520
+ * Keeps the same relative position inside the element. Returns the current box.
521
+ */
522
+ async followTarget(locator, box, timeout, moved) {
523
+ const now = moved ?? (await locator.boundingBox({ timeout: timeout ?? this.timeout }));
524
+ if (now && sameBox(now, box)) {
525
+ return now;
526
+ }
527
+ const current = await this.stableBox(locator, timeout);
528
+ const fx = box.width > 0 ? (this.position.x - box.x) / box.width : 0.5;
529
+ const fy = box.height > 0 ? (this.position.y - box.y) / box.height : 0.5;
530
+ const point = { x: current.x + current.width * fx, y: current.y + current.height * fy };
531
+ const distance = Math.hypot(point.x - this.position.x, point.y - this.position.y);
532
+ await this.moveCursor(point, Math.min(250, moveDuration(distance, this.options.cursor)));
533
+ return current;
534
+ }
535
+ /**
536
+ * Runs the Playwright actionability checks at the exact cursor point, without clicking.
537
+ */
538
+ async checkActionable(locator, box, timeout) {
539
+ const border = await locator.evaluate((element) => {
540
+ const style = getComputedStyle(element);
541
+ return {
542
+ x: parseFloat(style.borderLeftWidth) || 0,
543
+ y: parseFloat(style.borderTopWidth) || 0,
544
+ };
545
+ });
546
+ const { x, y } = this.position;
547
+ await locator.click({
548
+ trial: true,
549
+ position: { x: x - box.x - border.x, y: y - box.y - border.y },
550
+ timeout: timeout ?? this.timeout,
551
+ });
552
+ // The trial run moves the mouse to a rounded point: put it back on the exact point.
553
+ await this.page.mouse.move(x, y);
554
+ }
555
+ async pressButton(button, clickCount, modifiers = []) {
556
+ const hold = clickCount > 1
557
+ ? Math.min(this.options.pacing.pressDuration, 60)
558
+ : this.options.pacing.pressDuration;
559
+ for (const key of modifiers) {
560
+ await this.pace.input(() => this.page.keyboard.down(key));
561
+ }
562
+ try {
563
+ for (let count = 1; count <= clickCount; count++) {
564
+ if (count > 1) {
565
+ await this.pace.sleep(CAST_DEFAULTS.doubleClickGap);
566
+ }
567
+ await this.mouseDown(button, count);
568
+ await this.pace.sleep(hold);
569
+ await this.mouseUp(button, count);
570
+ }
571
+ }
572
+ finally {
573
+ for (const key of [...modifiers].reverse()) {
574
+ await this.pace.input(() => this.page.keyboard.up(key));
575
+ }
576
+ }
577
+ }
578
+ async mouseDown(button, clickCount) {
579
+ const { x, y } = this.position;
580
+ const t = await this.pace.input(() => this.page.mouse.down({ button, clickCount }));
581
+ this.timeline.push({ type: 'mouseDown', t, x, y, button });
582
+ }
583
+ async mouseUp(button, clickCount) {
584
+ const { x, y } = this.position;
585
+ const t = await this.pace.input(() => this.page.mouse.up({ button, clickCount }));
586
+ this.timeline.push({ type: 'mouseUp', t, x, y, button });
587
+ }
588
+ /**
589
+ * Moves the cursor along a human-like path, sampled every few milliseconds.
590
+ */
591
+ async moveCursor(to, duration, curvature = this.options.cursor.curvature, ease = moveEase) {
592
+ const from = this.position;
593
+ const distance = Math.hypot(to.x - from.x, to.y - from.y);
594
+ if (distance === 0) {
595
+ return;
596
+ }
597
+ const path = cursorPath(from, to, curvature, this.motionRandom, this.viewport);
598
+ const total = distance < 1 ? 0 : (duration ?? moveDuration(distance, this.options.cursor));
599
+ await this.pace.animate(total, MOVE_TICK, (progress, t) => {
600
+ const point = progress >= 1 ? to : path(ease(progress));
601
+ this.position = point;
602
+ this.cursorStyle.pointer = point;
603
+ this.timeline.sample(point, t);
604
+ return () => this.page.mouse.move(point.x, point.y);
605
+ });
606
+ }
607
+ /**
608
+ * Scrolls by wheel events at the cursor, with an ease-in-out over `duration`.
609
+ */
610
+ async wheel(dx, dy, duration) {
611
+ const target = { x: Math.round(dx), y: Math.round(dy) };
612
+ let planned = { x: 0, y: 0 };
613
+ const sent = { x: 0, y: 0 };
614
+ await this.pace.animate(duration, SCROLL_TICK, (progress) => {
615
+ const eased = easeInOutCubic(progress);
616
+ const total = { x: Math.round(target.x * eased), y: Math.round(target.y * eased) };
617
+ if (total.x === planned.x && total.y === planned.y) {
618
+ return undefined;
619
+ }
620
+ planned = total;
621
+ // A skipped step adds to the next one: the delta comes from what is already sent.
622
+ return () => {
623
+ const delta = { x: total.x - sent.x, y: total.y - sent.y };
624
+ sent.x = total.x;
625
+ sent.y = total.y;
626
+ return this.page.mouse.wheel(delta.x, delta.y);
627
+ };
628
+ });
629
+ }
630
+ /**
631
+ * Brings an element into view. Smooth: wheel steps over each scroll container, outer
632
+ * to inner, with the cursor moved over the container first. Falls back to an instant
633
+ * scroll when the wheel does not reach the element. Returns the last plan when the
634
+ * element is in view after a smooth scroll: it holds the element box.
635
+ */
636
+ async bringIntoView(locator, view) {
637
+ const { timeout } = view;
638
+ if (view.smooth) {
639
+ let last = { level: -1, distance: Infinity };
640
+ for (let i = 0; i < MAX_SCROLL_STEPS; i++) {
641
+ const plan = await locator.evaluate(planScroll, { block: view.block, ifNeeded: view.ifNeeded, cursor: this.position }, { timeout });
642
+ const distance = Math.hypot(plan.dx, plan.dy);
643
+ if (distance < 1 && plan.inView) {
644
+ return plan;
645
+ }
646
+ const stuck = plan.level === last.level && distance >= last.distance - 1;
647
+ if (plan.inFrame || distance < 1 || !plan.point || stuck) {
648
+ break;
649
+ }
650
+ last = { level: plan.level, distance };
651
+ await this.moveCursor(plan.point);
652
+ await this.wheel(plan.dx, plan.dy, view.duration ?? scrollDuration(distance));
653
+ await locator.evaluate(scrollIdle, undefined, { timeout });
654
+ }
655
+ }
656
+ await locator.scrollIntoViewIfNeeded({ timeout });
657
+ return undefined;
658
+ }
659
+ /**
660
+ * After Enter in `auto` indent mode: removes the indentation that the editor added and
661
+ * that `wanted` does not have. Returns how many characters of `wanted` are already there.
662
+ */
663
+ async alignIndent(wanted, delay, variance) {
664
+ const read = () => this.page.evaluate(caretLinePrefix).catch(() => null);
665
+ let present = await read();
666
+ if (present === null || /\S/.test(present)) {
667
+ return 0;
668
+ }
669
+ for (let presses = present.length; presses > 0 && !wanted.startsWith(present); presses--) {
670
+ await this.pace.sleep(typingDelay('', delay, variance, this.typingRandom));
671
+ await this.pace.input(() => this.page.keyboard.press('Backspace'));
672
+ const after = await read();
673
+ if (after === null || after.length >= present.length) {
674
+ return 0;
675
+ }
676
+ present = after;
677
+ }
678
+ return wanted.startsWith(present) ? present.length : 0;
679
+ }
680
+ }