dp-worker 0.1.6 → 0.1.7

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 (63) hide show
  1. package/builtin-skills/x.md +36 -28
  2. package/config.example.json +2 -0
  3. package/dist/agent/agent.js +1 -1
  4. package/dist/agent/agent.js.map +1 -1
  5. package/dist/agent/chat-engine.js +36 -13
  6. package/dist/agent/chat-engine.js.map +1 -1
  7. package/dist/agent/context.d.ts +2 -0
  8. package/dist/agent/context.js +4 -2
  9. package/dist/agent/context.js.map +1 -1
  10. package/dist/agent/task-runner.js +17 -16
  11. package/dist/agent/task-runner.js.map +1 -1
  12. package/dist/agent/tool-loop-detection.js +7 -3
  13. package/dist/agent/tool-loop-detection.js.map +1 -1
  14. package/dist/agent/tool-runner.js +2 -2
  15. package/dist/browser/actions.d.ts +26 -1
  16. package/dist/browser/actions.js +493 -242
  17. package/dist/browser/actions.js.map +1 -1
  18. package/dist/browser/chrome-process.d.ts +25 -3
  19. package/dist/browser/chrome-process.js +67 -13
  20. package/dist/browser/chrome-process.js.map +1 -1
  21. package/dist/browser/dispatch.js +32 -8
  22. package/dist/browser/dispatch.js.map +1 -1
  23. package/dist/browser/expect.d.ts +6 -1
  24. package/dist/browser/expect.js +32 -10
  25. package/dist/browser/expect.js.map +1 -1
  26. package/dist/browser/extension-relay.d.ts +9 -0
  27. package/dist/browser/extension-relay.js +579 -0
  28. package/dist/browser/extension-relay.js.map +1 -0
  29. package/dist/browser/manager.d.ts +11 -0
  30. package/dist/browser/manager.js +106 -26
  31. package/dist/browser/manager.js.map +1 -1
  32. package/dist/browser/page-outline.d.ts +36 -0
  33. package/dist/browser/page-outline.js +703 -0
  34. package/dist/browser/page-outline.js.map +1 -0
  35. package/dist/browser/script-runner.js +4 -2
  36. package/dist/browser/script-runner.js.map +1 -1
  37. package/dist/browser/selectors.js +10 -3
  38. package/dist/browser/selectors.js.map +1 -1
  39. package/dist/browser/snapshot.d.ts +19 -1
  40. package/dist/browser/snapshot.js +145 -24
  41. package/dist/browser/snapshot.js.map +1 -1
  42. package/dist/chrome-extension/omni-flow/background.js +304 -21
  43. package/dist/chrome-extension/omni-flow/connect.html +81 -0
  44. package/dist/chrome-extension/omni-flow/connect.js +43 -0
  45. package/dist/chrome-extension/omni-flow/content.js +13 -21
  46. package/dist/chrome-extension/omni-flow/inject.js +77 -56
  47. package/dist/chrome-extension/omni-flow/manifest.json +6 -3
  48. package/dist/config/center-config.js +2 -0
  49. package/dist/config/center-config.js.map +1 -1
  50. package/dist/config/types.d.ts +16 -2
  51. package/dist/config/types.js +21 -1
  52. package/dist/config/types.js.map +1 -1
  53. package/dist/index.js +11 -1
  54. package/dist/index.js.map +1 -1
  55. package/dist/llm/live-tool-result-guard.d.ts +16 -0
  56. package/dist/llm/live-tool-result-guard.js +57 -0
  57. package/dist/llm/live-tool-result-guard.js.map +1 -0
  58. package/dist/llm/message-optimizer.d.ts +10 -0
  59. package/dist/llm/message-optimizer.js +12 -0
  60. package/dist/llm/message-optimizer.js.map +1 -1
  61. package/dist/llm/tools.js +37 -11
  62. package/dist/llm/tools.js.map +1 -1
  63. package/package.json +1 -1
@@ -1,14 +1,36 @@
1
- import { takeSnapshot, getElementRef, resetRefs, } from "./snapshot.js";
2
- import { pasteText, humanType, humanMove, humanDrag, } from "./humanize.js";
1
+ import { takeSnapshot, formatCappedSnapshotText, getElementRef, resetRefs, resolveSnapshotLimit, } from "./snapshot.js";
2
+ import { pasteText, humanType, humanMove, humanDrag, humanScroll, } from "./humanize.js";
3
3
  import { normalizeSelector } from "./selectors.js";
4
4
  import { preflightEvaluateScript, wrapEvaluateScript } from "./dom-helpers.js";
5
5
  import { safeSliceHead, safeSliceTail } from "../utils/safe-slice.js";
6
6
  import { resolveSelector, locateRefWithRecovery, looksDestructive, refNotFoundMessage, } from "./locator-resolver.js";
7
7
  import { cleanupRunHandled, runBuiltinPageCleanups, } from "./builtin-page-cleanups.js";
8
+ import { waitForNoVisibleMatches } from "./expect.js";
9
+ import { DEFAULT_OUTLINE_MAX_CHARS } from "./page-outline.js";
8
10
  import fs from "node:fs";
9
11
  import path from "node:path";
10
12
  import crypto from "node:crypto";
11
13
  const DEFAULT_ACTION_DELAY = { min: 800, max: 3000 };
14
+ const EVALUATE_FALLBACK_DISABLED = "evaluate fallback disabled by browser.allowEvaluateFallbacks=false";
15
+ function evaluateFallbackDisabled(feature) {
16
+ return `${EVALUATE_FALLBACK_DISABLED}: ${feature}`;
17
+ }
18
+ function truncateSnapshotHeaderValue(value, maxChars) {
19
+ if (value.length <= maxChars)
20
+ return value;
21
+ return `${safeSliceHead(value, Math.max(0, maxChars - 15))}...[TRUNCATED]`;
22
+ }
23
+ function formatSnapshotHeader(title, url, limit) {
24
+ const fieldBudget = Math.max(80, Math.min(500, Math.floor(limit / 20)));
25
+ return `Page: ${truncateSnapshotHeaderValue(title, fieldBudget)}\nURL: ${truncateSnapshotHeaderValue(url, fieldBudget)}`;
26
+ }
27
+ function resolveOutlineSnapshotLimit(maxChars) {
28
+ if (maxChars === undefined || !Number.isFinite(maxChars) || maxChars <= 0) {
29
+ return DEFAULT_OUTLINE_MAX_CHARS;
30
+ }
31
+ return Math.min(Math.floor(maxChars), DEFAULT_OUTLINE_MAX_CHARS);
32
+ }
33
+ const OUTLINE_WRAPPER_TRUNCATED_HINT = "\n[...TRUNCATED]";
12
34
  const MAX_CONSOLE_MESSAGES = 1000;
13
35
  // Track which pages already have a console listener
14
36
  const trackedPages = new WeakSet();
@@ -54,24 +76,23 @@ function recentConsoleEntries(page, n) {
54
76
  return buf.slice(-n);
55
77
  }
56
78
  // refNotFoundMessage moved to ./locator-resolver.
57
- /**
58
- * Tag we stamp on the editable element we ultimately focus, so the
59
- * post-insertion verifier can read the same node back without depending on
60
- * `document.activeElement` (which loses focus when the verifier itself
61
- * does anything that ticks the event loop). Cleared on snapshot reset.
62
- */
63
- const EDIT_TARGET_ATTR = "data-dipclaw-edit-target";
79
+ function makePrivateWindowKey() {
80
+ return `__${crypto.randomBytes(12).toString("hex")}`;
81
+ }
82
+ const CLICK_PROBE_STORE_KEY = makePrivateWindowKey();
83
+ const HOVER_PROBE_STORE_KEY = makePrivateWindowKey();
84
+ const KEY_PROBE_STORE_KEY = makePrivateWindowKey();
85
+ const CLICK_TARGET_ATTR = `data-a${crypto.randomBytes(8).toString("hex")}`;
64
86
  /**
65
87
  * After clicking the resolved locator to focus it, make sure we actually
66
88
  * landed on an editable node. If not, search the original locator's subtree
67
89
  * for a single editable descendant and focus that instead.
68
90
  *
69
- * Stamps `EDIT_TARGET_ATTR` on whatever we end up focusing so the verifier
70
- * can read the same node back regardless of subsequent focus changes
71
- * (clicking outside the editor for any reason, snapshot taking focus, etc.).
91
+ * Returns a handle to the focused editable so the verifier can read the same
92
+ * node back without writing a page-visible marker attribute.
72
93
  */
73
- async function ensureEditableTarget(page, locator) {
74
- const result = await locator.first().evaluate((root, attr) => {
94
+ async function ensureEditableTarget(locator) {
95
+ const resultHandle = await locator.first().evaluateHandle((root) => {
75
96
  // Arrow form (not `function describe()`) is intentional: tsx/esbuild
76
97
  // wraps named function declarations with __name() to preserve
77
98
  // Function.name. When this body is serialized for Playwright
@@ -121,10 +142,6 @@ async function ensureEditableTarget(page, locator) {
121
142
  return false;
122
143
  };
123
144
  const root_ = root;
124
- // Clear any stale stamp on the document — only one edit target at a time.
125
- document
126
- .querySelectorAll(`[${attr}]`)
127
- .forEach((n) => n.removeAttribute(attr));
128
145
  let target = null;
129
146
  let diag = describe(root_);
130
147
  if (isEditable(root_)) {
@@ -170,7 +187,6 @@ async function ensureEditableTarget(page, locator) {
170
187
  diagnostic: describe(root_),
171
188
  };
172
189
  }
173
- target.setAttribute(attr, "1");
174
190
  // Focus the editable. A second focus() is a no-op on the host page
175
191
  // when it's already focused; cheap insurance for the wrapper case.
176
192
  try {
@@ -183,18 +199,35 @@ async function ensureEditableTarget(page, locator) {
183
199
  }
184
200
  return {
185
201
  ok: true,
202
+ target,
186
203
  isRichEditor: isRich(target),
187
204
  diagnostic: diag,
188
205
  };
189
- }, EDIT_TARGET_ATTR);
190
- if (!result.ok) {
191
- return { ok: false, message: result.message, diagnostic: result.diagnostic };
206
+ });
207
+ const props = await resultHandle.getProperties();
208
+ const ok = await props.get("ok")?.jsonValue();
209
+ const diagnostic = await props.get("diagnostic")?.jsonValue();
210
+ const message = await props.get("message")?.jsonValue();
211
+ if (ok !== true) {
212
+ await resultHandle.dispose().catch(() => { });
213
+ return { ok: false, message, diagnostic };
214
+ }
215
+ const targetHandle = props.get("target")?.asElement();
216
+ if (!targetHandle) {
217
+ await resultHandle.dispose().catch(() => { });
218
+ return {
219
+ ok: false,
220
+ message: "resolved editable target could not be retained for verification",
221
+ diagnostic,
222
+ };
192
223
  }
224
+ const isRichEditor = (await props.get("isRichEditor")?.jsonValue()) === true;
225
+ await resultHandle.dispose().catch(() => { });
193
226
  return {
194
227
  ok: true,
195
- handleSelector: `[${EDIT_TARGET_ATTR}="1"]`,
196
- isRichEditor: result.isRichEditor === true,
197
- diagnostic: result.diagnostic,
228
+ handle: targetHandle,
229
+ isRichEditor,
230
+ diagnostic,
198
231
  };
199
232
  }
200
233
  async function insertText(page, method, text) {
@@ -209,9 +242,10 @@ async function insertText(page, method, text) {
209
242
  * Empty the editable's contents reliably across plain inputs and
210
243
  * framework-controlled rich editors.
211
244
  *
212
- * Plain <input>/<textarea>: write "" through the prototype's native value
213
- * setter (same React-tracker bypass `pasteText` uses) and emit input+change.
214
- * No keystroke needed.
245
+ * Plain <input>/<textarea>: when unsafe fallbacks are explicitly enabled,
246
+ * write "" through the prototype's native value setter (same React-tracker
247
+ * bypass `pasteText` uses) and emit input+change. Otherwise use keyboard
248
+ * select-all/delete only.
215
249
  *
216
250
  * Rich editor (contenteditable / Draft.js / Lexical / ProseMirror): focus
217
251
  * the editable, then press Cmd+A + Delete via real CDP keystrokes. Cmd+A
@@ -234,43 +268,45 @@ async function insertText(page, method, text) {
234
268
  * Caller must ensure blocking modal overlays are closed so the Cmd+A
235
269
  * keystroke reaches the editor instead of being trapped by a dialog.
236
270
  */
237
- async function forceClear(page, handleSelector) {
238
- await runBuiltinPageCleanups(page, "before-edit");
239
- const handled = await page.evaluate((sel) => {
240
- const el = document.querySelector(sel);
241
- if (!el)
242
- return false;
243
- try {
244
- el.focus({ preventScroll: false });
245
- }
246
- catch {
247
- // Non-tabbable contenteditable: ignore, the caller's click already
248
- // focused it.
249
- }
250
- const tag = el.tagName;
251
- if (tag === "INPUT" || tag === "TEXTAREA") {
252
- const input = el;
253
- const proto = tag === "INPUT"
254
- ? HTMLInputElement.prototype
255
- : HTMLTextAreaElement.prototype;
256
- const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
257
- if (setter) {
258
- setter.call(input, "");
271
+ async function forceClear(page, handle, allowEvaluateFallbacks) {
272
+ if (allowEvaluateFallbacks) {
273
+ await runBuiltinPageCleanups(page, "before-edit");
274
+ }
275
+ const handled = allowEvaluateFallbacks
276
+ ? await handle.evaluate((el) => {
277
+ try {
278
+ el.focus({ preventScroll: false });
259
279
  }
260
- else {
261
- input.value = "";
280
+ catch {
281
+ // Non-tabbable contenteditable: ignore, the caller's click already
282
+ // focused it.
283
+ }
284
+ const tag = el.tagName;
285
+ if (tag === "INPUT" || tag === "TEXTAREA") {
286
+ const input = el;
287
+ const proto = tag === "INPUT"
288
+ ? HTMLInputElement.prototype
289
+ : HTMLTextAreaElement.prototype;
290
+ const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
291
+ if (setter) {
292
+ setter.call(input, "");
293
+ }
294
+ else {
295
+ input.value = "";
296
+ }
297
+ input.dispatchEvent(new InputEvent("input", {
298
+ bubbles: true,
299
+ inputType: "deleteContentBackward",
300
+ }));
301
+ input.dispatchEvent(new Event("change", { bubbles: true }));
302
+ return true;
262
303
  }
263
- input.dispatchEvent(new InputEvent("input", {
264
- bubbles: true,
265
- inputType: "deleteContentBackward",
266
- }));
267
- input.dispatchEvent(new Event("change", { bubbles: true }));
268
- return true;
269
- }
270
- return false;
271
- }, handleSelector);
304
+ return false;
305
+ })
306
+ : false;
272
307
  if (handled)
273
308
  return;
309
+ await handle.focus().catch(() => { });
274
310
  const mod = process.platform === "darwin" ? "Meta" : "Control";
275
311
  await page.keyboard.press(`${mod}+a`);
276
312
  // Small gap so the editor's keybinding has committed select-all into its
@@ -281,10 +317,8 @@ async function forceClear(page, handleSelector) {
281
317
  // from the DOM before the next insert runs on top of it.
282
318
  await new Promise((r) => setTimeout(r, 100));
283
319
  }
284
- async function dumpEditorDiagnostics(page, handleSelector, expectedText) {
285
- return await page.evaluate(({ sel, expected }) => {
286
- const all = document.querySelectorAll(sel);
287
- const el = all[0];
320
+ async function dumpEditorDiagnostics(handle, expectedText) {
321
+ return await handle.evaluate((el, expected) => {
288
322
  // Inline mirror of normalizeForCompare. Use \u escapes (not literal
289
323
  // chars) so TS source parser doesn't trip on U+2028/U+2029 which
290
324
  // are line terminators in ECMAScript syntax even inside a string.
@@ -298,22 +332,6 @@ async function dumpEditorDiagnostics(page, handleSelector, expectedText) {
298
332
  .replace(/[ \t]*\n[ \t]*/g, "\n")
299
333
  .replace(/\n{3,}/g, "\n\n")
300
334
  .trim();
301
- if (!el) {
302
- return {
303
- readSelector: sel,
304
- resolvedTag: "(missing)",
305
- resolvedClass: "",
306
- resolvedRole: null,
307
- isContentEditable: false,
308
- fullInnerText: "",
309
- innerTextLength: 0,
310
- outerHtmlSnippet: "",
311
- outerHtmlLength: 0,
312
- matchOffsets: [],
313
- blockCount: 0,
314
- multipleMatches: false,
315
- };
316
- }
317
335
  const innerText = el.innerText ?? "";
318
336
  const innerTextNorm = norm(innerText);
319
337
  const expectedNorm = norm(expected);
@@ -332,7 +350,6 @@ async function dumpEditorDiagnostics(page, handleSelector, expectedText) {
332
350
  }
333
351
  const html = el.outerHTML ?? "";
334
352
  return {
335
- readSelector: sel,
336
353
  resolvedTag: el.tagName.toLowerCase(),
337
354
  resolvedClass: el.className || "",
338
355
  resolvedRole: el.getAttribute("role"),
@@ -343,9 +360,9 @@ async function dumpEditorDiagnostics(page, handleSelector, expectedText) {
343
360
  outerHtmlLength: html.length,
344
361
  matchOffsets: offsets,
345
362
  blockCount: el.querySelectorAll("[data-block='true']").length,
346
- multipleMatches: all.length > 1,
363
+ multipleMatches: false,
347
364
  };
348
- }, { sel: handleSelector, expected: expectedText });
365
+ }, expectedText);
349
366
  }
350
367
  /**
351
368
  * Normalize text for comparison. Deliberately narrow: only changes that the
@@ -403,8 +420,8 @@ export function urlKey(u) {
403
420
  * Read the editable's current value and any anchor hrefs inside it (rich
404
421
  * editors only). Returned as raw strings; normalization is the caller's job.
405
422
  */
406
- async function readEditable(page, handleSelector) {
407
- return page.locator(handleSelector).first().evaluate((el) => {
423
+ async function readEditable(handle) {
424
+ return handle.evaluate((el) => {
408
425
  if (el instanceof HTMLInputElement ||
409
426
  el instanceof HTMLTextAreaElement) {
410
427
  return { value: el.value, anchors: [] };
@@ -417,6 +434,25 @@ async function readEditable(page, handleSelector) {
417
434
  return { value, anchors };
418
435
  });
419
436
  }
437
+ export function shouldForceClearBeforeTyping(snapshot) {
438
+ return snapshot.value.length > 0 || snapshot.anchors.length > 0;
439
+ }
440
+ export function shouldAllowPasteMethod(input) {
441
+ return input.isRichEditor || input.allowEvaluateFallbacks;
442
+ }
443
+ async function forceClearIfNeeded(page, handle, allowEvaluateFallbacks) {
444
+ try {
445
+ const snapshot = await readEditable(handle);
446
+ if (!shouldForceClearBeforeTyping(snapshot)) {
447
+ return false;
448
+ }
449
+ }
450
+ catch {
451
+ // If readback fails, keep the conservative legacy behavior.
452
+ }
453
+ await forceClear(page, handle, allowEvaluateFallbacks);
454
+ return true;
455
+ }
420
456
  /**
421
457
  * One-shot evaluation of expected vs actual. Pure function over the
422
458
  * already-read snapshot (no DOM access), so the polling loop can iterate
@@ -545,8 +581,8 @@ export function evaluateMatch(expectedText, expectedUrls, value, anchorHrefs) {
545
581
  * - status="missing_text" — body may still be rendering
546
582
  * - status="ok_url_warning" — link card may still be materializing
547
583
  */
548
- async function verifyInsertedText(handleSelector, page, text, opts = {}) {
549
- if (!handleSelector || text === "") {
584
+ async function verifyInsertedText(handle, text, opts = {}) {
585
+ if (!handle || text === "") {
550
586
  return { ok: true, status: "ok", lastValue: "" };
551
587
  }
552
588
  const expectedUrls = extractUrls(text)
@@ -572,7 +608,7 @@ async function verifyInsertedText(handleSelector, page, text, opts = {}) {
572
608
  };
573
609
  while (true) {
574
610
  try {
575
- const { value, anchors } = await readEditable(page, handleSelector);
611
+ const { value, anchors } = await readEditable(handle);
576
612
  const result = evaluateMatch(text, expectedUrls, value, anchors);
577
613
  last = result;
578
614
  if (result.status === "ok" || result.status === "duplicated") {
@@ -635,17 +671,11 @@ async function resolveRefOrError(locator, ref, label = "element", selectorParam
635
671
  }
636
672
  return null;
637
673
  }
638
- /* -------------------------------------------------------------------------- */
639
- /* Generic safe click helpers */
640
- /* -------------------------------------------------------------------------- */
641
- const CLICK_TARGET_ATTR = "data-dipclaw-click-target";
642
674
  function anyCleanupHandled(runs) {
643
675
  return runs.some(cleanupRunHandled);
644
676
  }
645
677
  function makeClickStamp() {
646
- return `dipclaw-${Date.now().toString(36)}-${Math.random()
647
- .toString(36)
648
- .slice(2)}`;
678
+ return `${Date.now().toString(36)}-${crypto.randomBytes(8).toString("hex")}`;
649
679
  }
650
680
  function clickStampSelector(stamp) {
651
681
  return `[${CLICK_TARGET_ATTR}=${JSON.stringify(stamp)}]`;
@@ -729,10 +759,10 @@ async function probeClickTarget(page, selector) {
729
759
  }, selector);
730
760
  }
731
761
  async function installClickEventProbe(page, selector, probeId) {
732
- await page.evaluate(({ sel, id }) => {
762
+ await page.evaluate(({ sel, id, storeKey }) => {
733
763
  const target = document.querySelector(sel);
734
764
  const w = window;
735
- w.__dipclawClickProbes ??= {};
765
+ const store = (w[storeKey] ??= {});
736
766
  const state = {
737
767
  pointerdownOnTarget: false,
738
768
  pointerupOnTarget: false,
@@ -757,28 +787,29 @@ async function installClickEventProbe(page, selector, probeId) {
757
787
  state.clickTargetRole = el?.getAttribute?.("role") ?? null;
758
788
  state.clickTargetAriaLabel = el?.getAttribute?.("aria-label") ?? null;
759
789
  }, { capture: true, signal: controller.signal });
760
- w.__dipclawClickProbes[id] = {
790
+ store[id] = {
761
791
  state,
762
792
  controller,
763
793
  };
764
- }, { sel: selector, id: probeId });
794
+ }, { sel: selector, id: probeId, storeKey: CLICK_PROBE_STORE_KEY });
765
795
  }
766
796
  async function readAndClearClickEventProbe(page, probeId) {
767
- return await page.evaluate((id) => {
797
+ return await page.evaluate(({ id, storeKey }) => {
768
798
  const w = window;
769
- const probe = w.__dipclawClickProbes?.[id];
799
+ const store = w[storeKey];
800
+ const probe = store?.[id];
770
801
  if (!probe)
771
802
  return undefined;
772
803
  probe.controller?.abort();
773
- delete w.__dipclawClickProbes?.[id];
804
+ delete store?.[id];
774
805
  return probe.state;
775
- }, probeId);
806
+ }, { id: probeId, storeKey: CLICK_PROBE_STORE_KEY });
776
807
  }
777
808
  async function installHoverEventProbe(page, selector, probeId) {
778
- await page.evaluate(({ sel, id }) => {
809
+ await page.evaluate(({ sel, id, storeKey }) => {
779
810
  const target = document.querySelector(sel);
780
811
  const w = window;
781
- w.__dipclawHoverProbes ??= {};
812
+ const store = (w[storeKey] ??= {});
782
813
  const state = {
783
814
  pointeroverOnTarget: false,
784
815
  pointerenterOnTarget: false,
@@ -814,19 +845,20 @@ async function installHoverEventProbe(page, selector, probeId) {
814
845
  capture: true,
815
846
  signal: controller.signal,
816
847
  });
817
- w.__dipclawHoverProbes[id] = { state, controller };
818
- }, { sel: selector, id: probeId });
848
+ store[id] = { state, controller };
849
+ }, { sel: selector, id: probeId, storeKey: HOVER_PROBE_STORE_KEY });
819
850
  }
820
851
  async function readAndClearHoverEventProbe(page, probeId) {
821
- return await page.evaluate((id) => {
852
+ return await page.evaluate(({ id, storeKey }) => {
822
853
  const w = window;
823
- const probe = w.__dipclawHoverProbes?.[id];
854
+ const store = w[storeKey];
855
+ const probe = store?.[id];
824
856
  if (!probe)
825
857
  return undefined;
826
858
  probe.controller?.abort();
827
- delete w.__dipclawHoverProbes?.[id];
859
+ delete store?.[id];
828
860
  return probe.state;
829
- }, probeId);
861
+ }, { id: probeId, storeKey: HOVER_PROBE_STORE_KEY });
830
862
  }
831
863
  function hoverEventReachedTarget(probe) {
832
864
  // Any of these means React-style hover handlers had a chance to fire.
@@ -872,9 +904,9 @@ async function evaluateDomHover(page, selector) {
872
904
  }, selector);
873
905
  }
874
906
  async function installKeyEventProbe(page, probeId) {
875
- await page.evaluate((id) => {
907
+ await page.evaluate(({ id, storeKey }) => {
876
908
  const w = window;
877
- w.__dipclawKeyProbes ??= {};
909
+ const store = (w[storeKey] ??= {});
878
910
  const state = {
879
911
  keydownFired: false,
880
912
  keyupFired: false,
@@ -894,19 +926,20 @@ async function installKeyEventProbe(page, probeId) {
894
926
  document.addEventListener("keyup", () => {
895
927
  state.keyupFired = true;
896
928
  }, { capture: true, signal: controller.signal });
897
- w.__dipclawKeyProbes[id] = { state, controller };
898
- }, probeId);
929
+ store[id] = { state, controller };
930
+ }, { id: probeId, storeKey: KEY_PROBE_STORE_KEY });
899
931
  }
900
932
  async function readAndClearKeyEventProbe(page, probeId) {
901
- return await page.evaluate((id) => {
933
+ return await page.evaluate(({ id, storeKey }) => {
902
934
  const w = window;
903
- const probe = w.__dipclawKeyProbes?.[id];
935
+ const store = w[storeKey];
936
+ const probe = store?.[id];
904
937
  if (!probe)
905
938
  return undefined;
906
939
  probe.controller?.abort();
907
- delete w.__dipclawKeyProbes?.[id];
940
+ delete store?.[id];
908
941
  return probe.state;
909
- }, probeId);
942
+ }, { id: probeId, storeKey: KEY_PROBE_STORE_KEY });
910
943
  }
911
944
  async function evaluateDomKey(page, key) {
912
945
  return await page.evaluate((k) => {
@@ -1061,9 +1094,12 @@ async function evaluateDomClick(page, selector) {
1061
1094
  * Same shape as dispatchSafeClick: physical attempt first, probe the
1062
1095
  * renderer for actual delivery, fall back to JS dispatch on event-miss.
1063
1096
  */
1064
- async function dispatchSafeKeyPress(page, key) {
1065
- let probeId = makeClickStamp();
1066
- await installKeyEventProbe(page, probeId);
1097
+ async function dispatchSafeKeyPress(page, key, allowEvaluateFallbacks) {
1098
+ let probeId;
1099
+ if (allowEvaluateFallbacks) {
1100
+ probeId = makeClickStamp();
1101
+ await installKeyEventProbe(page, probeId);
1102
+ }
1067
1103
  let physicalError;
1068
1104
  try {
1069
1105
  await page.keyboard.press(key);
@@ -1071,8 +1107,9 @@ async function dispatchSafeKeyPress(page, key) {
1071
1107
  catch (err) {
1072
1108
  physicalError = err instanceof Error ? err.message : String(err);
1073
1109
  }
1074
- const eventProbe = await readAndClearKeyEventProbe(page, probeId).catch(() => undefined);
1075
- probeId = undefined;
1110
+ const eventProbe = probeId
1111
+ ? await readAndClearKeyEventProbe(page, probeId).catch(() => undefined)
1112
+ : undefined;
1076
1113
  let fallbackUsed = false;
1077
1114
  let dispatchedVia = "keyboard";
1078
1115
  let fallbackError;
@@ -1080,15 +1117,21 @@ async function dispatchSafeKeyPress(page, key) {
1080
1117
  // either it threw, or the in-page probe never saw a keydown (CDP synthetic
1081
1118
  // input was dropped). If needsFallback is true and the DOM fallback didn't
1082
1119
  // succeed, the press did NOT happen — callers must see ok:false.
1083
- const needsFallback = !!physicalError || (!!eventProbe && !eventProbe.keydownFired);
1120
+ const needsFallback = !!physicalError ||
1121
+ (allowEvaluateFallbacks && !!eventProbe && !eventProbe.keydownFired);
1084
1122
  if (needsFallback) {
1085
- const dom = await evaluateDomKey(page, key);
1086
- if (dom.ok) {
1087
- fallbackUsed = true;
1088
- dispatchedVia = "dom";
1123
+ if (!allowEvaluateFallbacks) {
1124
+ fallbackError = EVALUATE_FALLBACK_DISABLED;
1089
1125
  }
1090
1126
  else {
1091
- fallbackError = dom.reason;
1127
+ const dom = await evaluateDomKey(page, key);
1128
+ if (dom.ok) {
1129
+ fallbackUsed = true;
1130
+ dispatchedVia = "dom";
1131
+ }
1132
+ else {
1133
+ fallbackError = dom.reason;
1134
+ }
1092
1135
  }
1093
1136
  }
1094
1137
  return {
@@ -1115,10 +1158,41 @@ async function withKeyboardModifiers(page, modifiers, fn) {
1115
1158
  }
1116
1159
  async function dispatchSafeClick(page, locator, opts) {
1117
1160
  const dispatch = opts.dispatch ?? "mouse";
1161
+ const allowPageInstrumentation = opts.allowPageInstrumentation === true;
1118
1162
  let probe;
1119
1163
  let eventProbe;
1120
1164
  let probeId;
1121
1165
  try {
1166
+ if (!allowPageInstrumentation) {
1167
+ if (dispatch === "dom") {
1168
+ return {
1169
+ ok: false,
1170
+ dispatchedVia: "dom",
1171
+ message: evaluateFallbackDisabled('dispatch="dom"'),
1172
+ fallbackReason: "evaluate-fallback-disabled",
1173
+ };
1174
+ }
1175
+ const box = await locator.boundingBox();
1176
+ if (!box || box.width <= 0 || box.height <= 0) {
1177
+ return {
1178
+ ok: false,
1179
+ dispatchedVia: "mouse",
1180
+ message: "click target does not have a visible bounding box",
1181
+ fallbackReason: "no-bounding-box",
1182
+ };
1183
+ }
1184
+ const x = box.x + box.width * (0.35 + Math.random() * 0.3);
1185
+ const y = box.y + box.height * (0.35 + Math.random() * 0.3);
1186
+ await withKeyboardModifiers(page, opts.modifiers, () => page.mouse.click(x, y, {
1187
+ delay: Math.random() * 20,
1188
+ button: opts.button ?? "left",
1189
+ }));
1190
+ return {
1191
+ ok: true,
1192
+ dispatchedVia: "mouse",
1193
+ probe: { found: true, x, y, onTarget: true },
1194
+ };
1195
+ }
1122
1196
  let stamp = makeClickStamp();
1123
1197
  await stampClickTarget(locator, stamp);
1124
1198
  let targetSelector = clickStampSelector(stamp);
@@ -1239,7 +1313,9 @@ async function dispatchSafeClick(page, locator, opts) {
1239
1313
  };
1240
1314
  }
1241
1315
  finally {
1242
- await clearClickTargetStamps(page);
1316
+ if (allowPageInstrumentation) {
1317
+ await clearClickTargetStamps(page);
1318
+ }
1243
1319
  }
1244
1320
  }
1245
1321
  /* -------------------------------------------------------------------------- */
@@ -1564,10 +1640,13 @@ export class BrowserActions {
1564
1640
  dialogArmId = 0;
1565
1641
  uploadArmId = 0;
1566
1642
  attachmentsDir = null;
1567
- constructor(browser, actionDelay, attachmentsDir) {
1643
+ allowEvaluateFallbacksEnabled;
1644
+ constructor(browser, actionDelay, attachmentsDir, options) {
1568
1645
  this.browser = browser;
1569
1646
  this.actionDelay = actionDelay ?? DEFAULT_ACTION_DELAY;
1570
1647
  this.attachmentsDir = attachmentsDir ?? null;
1648
+ this.allowEvaluateFallbacksEnabled =
1649
+ options?.allowEvaluateFallbacks ?? false;
1571
1650
  }
1572
1651
  /**
1573
1652
  * Auto-inject a random delay between consecutive browser actions
@@ -1589,6 +1668,9 @@ export class BrowserActions {
1589
1668
  async getPage() {
1590
1669
  return this.browser.getActivePage();
1591
1670
  }
1671
+ allowEvaluateFallbacks() {
1672
+ return this.allowEvaluateFallbacksEnabled;
1673
+ }
1592
1674
  setLogger(logger) {
1593
1675
  this.logger = logger;
1594
1676
  }
@@ -1639,7 +1721,25 @@ export class BrowserActions {
1639
1721
  selector: opts.selector,
1640
1722
  elements: result.elementRefs.size,
1641
1723
  });
1642
- return `Page: ${title}\nURL: ${url}\n\n${result.text}`;
1724
+ const mode = opts.mode ?? "full";
1725
+ if (mode === "outline") {
1726
+ const limit = resolveOutlineSnapshotLimit(opts.maxChars);
1727
+ return formatCappedSnapshotText(result.text, {
1728
+ limit,
1729
+ prefix: formatSnapshotHeader(title, url, limit),
1730
+ truncatedHint: OUTLINE_WRAPPER_TRUNCATED_HINT,
1731
+ preserveTail: true,
1732
+ });
1733
+ }
1734
+ const { limit, notice } = resolveSnapshotLimit(opts, mode);
1735
+ const body = notice && result.text.startsWith(`${notice}\n`)
1736
+ ? result.text.slice(notice.length + 1)
1737
+ : result.text;
1738
+ return formatCappedSnapshotText(body, {
1739
+ limit,
1740
+ notice,
1741
+ prefix: formatSnapshotHeader(title, url, limit),
1742
+ });
1643
1743
  }
1644
1744
  async screenshot(opts) {
1645
1745
  const page = await this.browser.getActivePage();
@@ -1966,6 +2066,21 @@ export class BrowserActions {
1966
2066
  else {
1967
2067
  return "Error: click requires ref or selector.";
1968
2068
  }
2069
+ if (options?.dispatch === "dom" && !this.allowEvaluateFallbacks()) {
2070
+ const msg = evaluateFallbackDisabled('dispatch="dom"');
2071
+ this.logger?.log("click", {
2072
+ ref,
2073
+ selector,
2074
+ label,
2075
+ ...(selectorUsed ? { selectorUsed } : {}),
2076
+ ...(refUsed && refUsed !== ref ? { refUsed } : {}),
2077
+ ...(recoveredVia ? { recoveredVia } : {}),
2078
+ ...(options ?? {}),
2079
+ dispatchedVia: "dom",
2080
+ error: msg,
2081
+ }, false);
2082
+ return `Error clicking ${label}: ${msg}`;
2083
+ }
1969
2084
  try {
1970
2085
  await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
1971
2086
  // Human bezier mouse trail to a random point inside the target box.
@@ -2005,10 +2120,12 @@ export class BrowserActions {
2005
2120
  modifiers: options?.modifiers,
2006
2121
  dispatch: options?.dispatch ?? "mouse",
2007
2122
  purpose: "click",
2123
+ allowPageInstrumentation: this.allowEvaluateFallbacks(),
2008
2124
  });
2009
2125
  if (!safeClickResult.ok &&
2010
2126
  safeClickResult.fallbackReason === "event-miss" &&
2011
- (options?.dispatch ?? "mouse") === "mouse") {
2127
+ (options?.dispatch ?? "mouse") === "mouse" &&
2128
+ this.allowEvaluateFallbacks()) {
2012
2129
  eventMissCleanupRuns = await runBuiltinPageCleanups(page, "after-click-event-miss");
2013
2130
  if (eventMissCleanupRuns.length > 0) {
2014
2131
  this.logger?.log("page_cleanup", {
@@ -2024,6 +2141,7 @@ export class BrowserActions {
2024
2141
  modifiers: options?.modifiers,
2025
2142
  dispatch: "mouse",
2026
2143
  purpose: "click",
2144
+ allowPageInstrumentation: this.allowEvaluateFallbacks(),
2027
2145
  });
2028
2146
  }
2029
2147
  }
@@ -2126,13 +2244,16 @@ export class BrowserActions {
2126
2244
  }
2127
2245
  const clear = opts.clear ?? true;
2128
2246
  const explicitMethod = opts.method;
2247
+ const allowEvaluateFallbacks = this.allowEvaluateFallbacks();
2129
2248
  try {
2130
- const cleanup = await runBuiltinPageCleanups(page, "before-edit");
2131
- if (cleanup.length > 0) {
2132
- this.logger?.log("page_cleanup", {
2133
- stage: "before-edit",
2134
- runs: cleanup,
2135
- }, cleanup.every((run) => run.ok));
2249
+ if (allowEvaluateFallbacks) {
2250
+ const cleanup = await runBuiltinPageCleanups(page, "before-edit");
2251
+ if (cleanup.length > 0) {
2252
+ this.logger?.log("page_cleanup", {
2253
+ stage: "before-edit",
2254
+ runs: cleanup,
2255
+ }, cleanup.every((run) => run.ok));
2256
+ }
2136
2257
  }
2137
2258
  await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
2138
2259
  const box = await locator.boundingBox();
@@ -2148,11 +2269,14 @@ export class BrowserActions {
2148
2269
  button: "left",
2149
2270
  dispatch: "mouse",
2150
2271
  purpose: "type-focus",
2272
+ allowPageInstrumentation: allowEvaluateFallbacks,
2151
2273
  });
2152
2274
  let focusCleanupRuns = [];
2153
2275
  let focusRecoveredVia;
2154
2276
  let targetInfo;
2155
- if (!focusClick.ok && focusClick.fallbackReason === "event-miss") {
2277
+ if (!focusClick.ok &&
2278
+ focusClick.fallbackReason === "event-miss" &&
2279
+ allowEvaluateFallbacks) {
2156
2280
  focusCleanupRuns = await runBuiltinPageCleanups(page, "after-click-event-miss");
2157
2281
  if (focusCleanupRuns.length > 0) {
2158
2282
  this.logger?.log("page_cleanup", {
@@ -2167,6 +2291,7 @@ export class BrowserActions {
2167
2291
  button: "left",
2168
2292
  dispatch: "mouse",
2169
2293
  purpose: "type-focus",
2294
+ allowPageInstrumentation: allowEvaluateFallbacks,
2170
2295
  });
2171
2296
  if (retriedFocusClick.ok) {
2172
2297
  focusRecoveredVia = "cleanup-retry";
@@ -2175,8 +2300,9 @@ export class BrowserActions {
2175
2300
  }
2176
2301
  }
2177
2302
  if (!focusClick.ok) {
2178
- if (focusClick.fallbackReason === "event-miss") {
2179
- const recoveredTarget = await ensureEditableTarget(page, locator);
2303
+ if (focusClick.fallbackReason === "event-miss" &&
2304
+ allowEvaluateFallbacks) {
2305
+ const recoveredTarget = await ensureEditableTarget(locator);
2180
2306
  if (recoveredTarget.ok) {
2181
2307
  targetInfo = recoveredTarget;
2182
2308
  focusRecoveredVia = "dom-focus";
@@ -2209,7 +2335,7 @@ export class BrowserActions {
2209
2335
  // its keystrokes into the void. Inspect what we actually focused
2210
2336
  // and, if it's not editable, walk the locator's subtree for a
2211
2337
  // single editable descendant before failing.
2212
- targetInfo ??= await ensureEditableTarget(page, locator);
2338
+ targetInfo ??= await ensureEditableTarget(locator);
2213
2339
  if (!targetInfo.ok) {
2214
2340
  this.logger?.log("type", {
2215
2341
  ref,
@@ -2238,7 +2364,7 @@ export class BrowserActions {
2238
2364
  let baselineAnchorKey = "";
2239
2365
  if (!clear) {
2240
2366
  try {
2241
- const snap = await readEditable(page, targetInfo.handleSelector);
2367
+ const snap = await readEditable(targetInfo.handle);
2242
2368
  baselineValue = snap.value;
2243
2369
  baselineAnchorKey = snap.anchors.slice().sort().join("\u0001");
2244
2370
  }
@@ -2248,12 +2374,29 @@ export class BrowserActions {
2248
2374
  }
2249
2375
  }
2250
2376
  if (clear) {
2251
- await forceClear(page, targetInfo.handleSelector);
2377
+ await forceClearIfNeeded(page, targetInfo.handle, allowEvaluateFallbacks);
2252
2378
  }
2253
2379
  // Method selection: explicit > rich-editor auto-paste > keyboard.
2254
2380
  // Rich editors (Lexical/ProseMirror/Tiptap-style editors) drop
2255
2381
  // per-char keystrokes that aren't part of a paste/composition event.
2256
2382
  const method = explicitMethod ?? (targetInfo.isRichEditor ? "paste" : "keyboard");
2383
+ if (method === "paste" &&
2384
+ !shouldAllowPasteMethod({
2385
+ isRichEditor: targetInfo.isRichEditor === true,
2386
+ allowEvaluateFallbacks,
2387
+ })) {
2388
+ const msg = evaluateFallbackDisabled('method="paste" on plain inputs');
2389
+ this.logger?.log("type", {
2390
+ ref,
2391
+ selector,
2392
+ text,
2393
+ label,
2394
+ method,
2395
+ clear,
2396
+ error: msg,
2397
+ }, false);
2398
+ return `Error typing into ${label}: ${msg}`;
2399
+ }
2257
2400
  await insertText(page, method, text);
2258
2401
  // Read-back verification + recovery. `method` is a preference, not a
2259
2402
  // contract — by default we still attempt a one-shot retry when the
@@ -2280,7 +2423,7 @@ export class BrowserActions {
2280
2423
  // modal or animating. Most successes still land in <200ms.
2281
2424
  const verifyTimeoutMs = targetInfo.isRichEditor ? 2000 : 800;
2282
2425
  const allowFallback = opts.fallback !== false;
2283
- let verify = await verifyInsertedText(targetInfo.handleSelector, page, text, { timeoutMs: verifyTimeoutMs });
2426
+ let verify = await verifyInsertedText(targetInfo.handle, text, { timeoutMs: verifyTimeoutMs });
2284
2427
  let methodUsed = method;
2285
2428
  let fallbackUsed = false;
2286
2429
  // Same-method retry on duplicated. Only applicable with clear:true —
@@ -2291,9 +2434,9 @@ export class BrowserActions {
2291
2434
  verify.status === "duplicated" &&
2292
2435
  allowFallback &&
2293
2436
  clear) {
2294
- await forceClear(page, targetInfo.handleSelector);
2437
+ await forceClear(page, targetInfo.handle, allowEvaluateFallbacks);
2295
2438
  await insertText(page, method, text);
2296
- verify = await verifyInsertedText(targetInfo.handleSelector, page, text, { timeoutMs: verifyTimeoutMs });
2439
+ verify = await verifyInsertedText(targetInfo.handle, text, { timeoutMs: verifyTimeoutMs });
2297
2440
  // methodUsed unchanged; fallbackUsed stays false — this is the same
2298
2441
  // method, retried cleanly. Not a true alt-method fallback.
2299
2442
  }
@@ -2303,81 +2446,88 @@ export class BrowserActions {
2303
2446
  // stack a third copy on top of two.
2304
2447
  if (!verify.ok && verify.status !== "duplicated" && allowFallback) {
2305
2448
  const altMethod = method === "paste" ? "keyboard" : "paste";
2306
- // Pre-retry safety check.
2307
- //
2308
- // clear:true → we own the field's content; forceClear and retry
2309
- // with the alternate method. Clean.
2310
- //
2311
- // clear:false (append) → field contains the user's draft. We MUST
2312
- // NOT forceClear (would destroy the draft). But we
2313
- // also can't blindly retry: if the first attempt
2314
- // partially wrote (e.g. rich editor accepted some
2315
- // chars and dropped others), the field now holds
2316
- // `<draft><partial garbage>`. Appending the full text
2317
- // again would give `<draft><partial garbage><expected>`
2318
- // — the verifier's substring check would pass, and
2319
- // we'd return success on a corrupted field. So:
2320
- // compare the current value to the baseline we
2321
- // snapshotted. If it changed, partial write happened
2322
- // — bail to the caller with a clear diagnostic. If
2323
- // unchanged, the first attempt was a no-op and it's
2324
- // safe to retry with the alternate method.
2325
- if (clear) {
2326
- await forceClear(page, targetInfo.handleSelector);
2327
- }
2328
- else {
2329
- let currentValue = baselineValue;
2330
- let currentAnchorKey = baselineAnchorKey;
2331
- let readFailed = false;
2332
- try {
2333
- const snap = await readEditable(page, targetInfo.handleSelector);
2334
- currentValue = snap.value;
2335
- currentAnchorKey = snap.anchors.slice().sort().join("\u0001");
2336
- }
2337
- catch {
2338
- // Read failure is treated as "we can not prove the field is
2339
- // clean" - same as a partial-write case. Bail.
2340
- readFailed = true;
2449
+ const altMethodAllowed = altMethod !== "paste" ||
2450
+ shouldAllowPasteMethod({
2451
+ isRichEditor: targetInfo.isRichEditor === true,
2452
+ allowEvaluateFallbacks,
2453
+ });
2454
+ if (altMethodAllowed) {
2455
+ // Pre-retry safety check.
2456
+ //
2457
+ // clear:true → we own the field's content; forceClear and retry
2458
+ // with the alternate method. Clean.
2459
+ //
2460
+ // clear:false (append) → field contains the user's draft. We MUST
2461
+ // NOT forceClear (would destroy the draft). But we
2462
+ // also can't blindly retry: if the first attempt
2463
+ // partially wrote (e.g. rich editor accepted some
2464
+ // chars and dropped others), the field now holds
2465
+ // `<draft><partial garbage>`. Appending the full text
2466
+ // again would give `<draft><partial garbage><expected>`
2467
+ // — the verifier's substring check would pass, and
2468
+ // we'd return success on a corrupted field. So:
2469
+ // compare the current value to the baseline we
2470
+ // snapshotted. If it changed, partial write happened
2471
+ // — bail to the caller with a clear diagnostic. If
2472
+ // unchanged, the first attempt was a no-op and it's
2473
+ // safe to retry with the alternate method.
2474
+ if (clear) {
2475
+ await forceClearIfNeeded(page, targetInfo.handle, allowEvaluateFallbacks);
2341
2476
  }
2342
- const valueChanged = currentValue !== baselineValue;
2343
- const anchorsChanged = currentAnchorKey !== baselineAnchorKey;
2344
- if (readFailed || valueChanged || anchorsChanged) {
2345
- const partialKind = readFailed
2346
- ? "readback-failed"
2347
- : valueChanged && anchorsChanged
2348
- ? "value+anchor"
2349
- : valueChanged
2350
- ? "value"
2351
- : "anchor";
2352
- this.logger?.log("type", {
2353
- ref,
2354
- selector,
2355
- text,
2356
- label,
2357
- method,
2358
- clear,
2359
- verifyStatus: verify.status,
2360
- partialKind,
2361
- error: "append-mode partial write detected; refusing to fallback to avoid corrupting the field",
2362
- }, false);
2363
- const detail = readFailed
2364
- ? "post-attempt readback failed"
2365
- : anchorsChanged && !valueChanged
2366
- ? "first attempt added a link/anchor chip without visible text"
2367
- : "first attempt partially wrote into the field";
2368
- return (`Error typing into ${label}: ${detail} (clear:false / append mode); ` +
2369
- `refusing automatic fallback because retrying with the alternate ` +
2370
- `method would compound the corruption and could be reported as a ` +
2371
- `false success. Inspect the editable, clean up manually, then call ` +
2372
- `type again with the desired method. Resolved target: ${targetInfo.diagnostic}.`);
2477
+ else {
2478
+ let currentValue = baselineValue;
2479
+ let currentAnchorKey = baselineAnchorKey;
2480
+ let readFailed = false;
2481
+ try {
2482
+ const snap = await readEditable(targetInfo.handle);
2483
+ currentValue = snap.value;
2484
+ currentAnchorKey = snap.anchors.slice().sort().join("\u0001");
2485
+ }
2486
+ catch {
2487
+ // Read failure is treated as "we can not prove the field is
2488
+ // clean" - same as a partial-write case. Bail.
2489
+ readFailed = true;
2490
+ }
2491
+ const valueChanged = currentValue !== baselineValue;
2492
+ const anchorsChanged = currentAnchorKey !== baselineAnchorKey;
2493
+ if (readFailed || valueChanged || anchorsChanged) {
2494
+ const partialKind = readFailed
2495
+ ? "readback-failed"
2496
+ : valueChanged && anchorsChanged
2497
+ ? "value+anchor"
2498
+ : valueChanged
2499
+ ? "value"
2500
+ : "anchor";
2501
+ this.logger?.log("type", {
2502
+ ref,
2503
+ selector,
2504
+ text,
2505
+ label,
2506
+ method,
2507
+ clear,
2508
+ verifyStatus: verify.status,
2509
+ partialKind,
2510
+ error: "append-mode partial write detected; refusing to fallback to avoid corrupting the field",
2511
+ }, false);
2512
+ const detail = readFailed
2513
+ ? "post-attempt readback failed"
2514
+ : anchorsChanged && !valueChanged
2515
+ ? "first attempt added a link/anchor chip without visible text"
2516
+ : "first attempt partially wrote into the field";
2517
+ return (`Error typing into ${label}: ${detail} (clear:false / append mode); ` +
2518
+ `refusing automatic fallback because retrying with the alternate ` +
2519
+ `method would compound the corruption and could be reported as a ` +
2520
+ `false success. Inspect the editable, clean up manually, then call ` +
2521
+ `type again with the desired method. Resolved target: ${targetInfo.diagnostic}.`);
2522
+ }
2523
+ // First attempt was a no-op (editor dropped everything). Safe to
2524
+ // retry without clearing.
2373
2525
  }
2374
- // First attempt was a no-op (editor dropped everything). Safe to
2375
- // retry without clearing.
2526
+ await insertText(page, altMethod, text);
2527
+ verify = await verifyInsertedText(targetInfo.handle, text, { timeoutMs: verifyTimeoutMs });
2528
+ methodUsed = altMethod;
2529
+ fallbackUsed = true;
2376
2530
  }
2377
- await insertText(page, altMethod, text);
2378
- verify = await verifyInsertedText(targetInfo.handleSelector, page, text, { timeoutMs: verifyTimeoutMs });
2379
- methodUsed = altMethod;
2380
- fallbackUsed = true;
2381
2531
  }
2382
2532
  if (!verify.ok) {
2383
2533
  // Pull rich diagnostics so the failure log can disambiguate "true
@@ -2386,7 +2536,7 @@ export class BrowserActions {
2386
2536
  // effort — if the page is mid-navigation the read can throw.
2387
2537
  let diag;
2388
2538
  try {
2389
- diag = await dumpEditorDiagnostics(page, targetInfo.handleSelector, text);
2539
+ diag = await dumpEditorDiagnostics(targetInfo.handle, text);
2390
2540
  }
2391
2541
  catch (err) {
2392
2542
  diag = { error: err instanceof Error ? err.message : String(err) };
@@ -2439,7 +2589,7 @@ export class BrowserActions {
2439
2589
  // search flows).
2440
2590
  let submitResult;
2441
2591
  if (opts.submit) {
2442
- submitResult = await dispatchSafeKeyPress(page, "Enter");
2592
+ submitResult = await dispatchSafeKeyPress(page, "Enter", allowEvaluateFallbacks);
2443
2593
  }
2444
2594
  this.logger?.log("type", {
2445
2595
  ref,
@@ -2515,7 +2665,7 @@ export class BrowserActions {
2515
2665
  const clamped = Math.min(delayMs, 5000);
2516
2666
  await new Promise((r) => setTimeout(r, clamped));
2517
2667
  }
2518
- const r = await dispatchSafeKeyPress(page, key);
2668
+ const r = await dispatchSafeKeyPress(page, key, this.allowEvaluateFallbacks());
2519
2669
  if (!r.ok) {
2520
2670
  // ok=false covers two cases: physical threw, OR probe shows the key
2521
2671
  // never reached the renderer AND evaluateDomKey refused it (modifier
@@ -2578,34 +2728,62 @@ export class BrowserActions {
2578
2728
  let dispatchedVia = "mouse";
2579
2729
  try {
2580
2730
  await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
2581
- // Stamp the resolved element so the probe can match composedPath against
2582
- // a specific node (same pattern dispatchSafeClick uses).
2583
- const stamp = makeClickStamp();
2584
- await stampClickTarget(locator, stamp);
2585
- const stampSelector = clickStampSelector(stamp);
2586
- probeId = makeClickStamp();
2587
- await installHoverEventProbe(page, stampSelector, probeId);
2588
- // Human mouse movement before hover
2589
2731
  const box = await locator.boundingBox();
2590
- if (box) {
2591
- await humanMove(page, box.x + box.width * (0.3 + Math.random() * 0.4), box.y + box.height * (0.3 + Math.random() * 0.4));
2732
+ if (!box || box.width <= 0 || box.height <= 0) {
2733
+ const msg = "hover target does not have a visible bounding box";
2734
+ this.logger?.log("hover", { ref, selector, label, error: msg }, false);
2735
+ return `Error hovering ${label}: ${msg}`;
2736
+ }
2737
+ const hoverX = box.x + box.width * (0.3 + Math.random() * 0.4);
2738
+ const hoverY = box.y + box.height * (0.3 + Math.random() * 0.4);
2739
+ let stampSelector;
2740
+ if (this.allowEvaluateFallbacks()) {
2741
+ // Stamp the resolved element so the optional probe can match
2742
+ // composedPath against a specific node (same pattern dispatchSafeClick uses).
2743
+ const stamp = makeClickStamp();
2744
+ await stampClickTarget(locator, stamp);
2745
+ stampSelector = clickStampSelector(stamp);
2746
+ probeId = makeClickStamp();
2747
+ await installHoverEventProbe(page, stampSelector, probeId);
2748
+ }
2749
+ await humanMove(page, hoverX, hoverY);
2750
+ if (!this.allowEvaluateFallbacks()) {
2751
+ this.logger?.log("hover", {
2752
+ ref,
2753
+ selector,
2754
+ label,
2755
+ dispatchedVia,
2756
+ });
2757
+ return `Hovered ${label}`;
2592
2758
  }
2593
- await locator.hover({ timeout: 5000 });
2594
2759
  eventProbe = await readAndClearHoverEventProbe(page, probeId).catch(() => undefined);
2595
2760
  probeId = undefined;
2596
- // Same failure mode as click: Playwright reports hover ok, but no
2761
+ // Same failure mode as click: the coordinate hover ran, but no
2597
2762
  // pointer/mouse event reached the document. Fall back to JS-dispatched
2598
2763
  // hover events so React's onMouseEnter still fires (which is what
2599
2764
  // triggers X's hover-card fetch).
2600
2765
  //
2601
2766
  // Re-resolve and re-stamp the locator before the DOM dispatch — same
2602
2767
  // reason dispatchSafeClick re-stamps on event-miss: if React replaced
2603
- // the element between the initial stamp and locator.hover(), the
2768
+ // the element between the initial stamp and coordinate hover, the
2604
2769
  // original stamp is on a detached node and the original stampSelector
2605
2770
  // matches nothing. The physical hover may have actually succeeded on
2606
2771
  // the replacement; either way the DOM dispatch must target the live
2607
2772
  // node, not the detached one.
2608
2773
  if (eventProbe && !hoverEventReachedTarget(eventProbe)) {
2774
+ if (!this.allowEvaluateFallbacks()) {
2775
+ const msg = evaluateFallbackDisabled("DOM hover fallback");
2776
+ this.logger?.log("hover", {
2777
+ ref,
2778
+ selector,
2779
+ label,
2780
+ dispatchedVia,
2781
+ eventProbe,
2782
+ fallbackReason: "event-miss",
2783
+ fallbackError: msg,
2784
+ }, false);
2785
+ return `Error hovering ${label}: physical mouse event did not reach target and ${msg}`;
2786
+ }
2609
2787
  let fallbackSelector = stampSelector;
2610
2788
  try {
2611
2789
  const restamp = makeClickStamp();
@@ -2801,6 +2979,73 @@ export class BrowserActions {
2801
2979
  this.logger?.log("resize", { width, height });
2802
2980
  return `Viewport resized to ${width}x${height}`;
2803
2981
  }
2982
+ async scroll(ref, options, selector) {
2983
+ await this.interActionDelay();
2984
+ const page = await this.browser.getActivePage();
2985
+ let label = "page";
2986
+ if (ref || selector != null) {
2987
+ let locator;
2988
+ if (ref) {
2989
+ const r = await locateRefWithRecovery(page, ref, { destructive: false });
2990
+ if (!r.ok) {
2991
+ this.logger?.log("scroll", { ref, error: r.message }, false);
2992
+ return r.message;
2993
+ }
2994
+ locator = r.locator;
2995
+ label = r.label;
2996
+ }
2997
+ else if (selector != null) {
2998
+ const r = resolveSelector(page, selector);
2999
+ if (!r.ok) {
3000
+ this.logger?.log("scroll", { selector, error: r.error }, false);
3001
+ return r.error;
3002
+ }
3003
+ locator = r.locator;
3004
+ label = r.selector;
3005
+ }
3006
+ if (locator) {
3007
+ await locator.scrollIntoViewIfNeeded({ timeout: 5000 });
3008
+ const box = await locator.boundingBox();
3009
+ if (box) {
3010
+ await humanMove(page, box.x + box.width * (0.3 + Math.random() * 0.4), box.y + box.height * (0.3 + Math.random() * 0.4));
3011
+ }
3012
+ }
3013
+ }
3014
+ const amount = Math.min(Math.max(Math.round(options?.amount ?? 500), 1), 5000);
3015
+ let deltaX = Math.round(options?.deltaX ?? 0);
3016
+ let deltaY = Math.round(options?.deltaY ?? 0);
3017
+ if (deltaX === 0 && deltaY === 0) {
3018
+ switch (options?.direction ?? "down") {
3019
+ case "up":
3020
+ deltaY = -amount;
3021
+ break;
3022
+ case "left":
3023
+ deltaX = -amount;
3024
+ break;
3025
+ case "right":
3026
+ deltaX = amount;
3027
+ break;
3028
+ case "down":
3029
+ default:
3030
+ deltaY = amount;
3031
+ break;
3032
+ }
3033
+ }
3034
+ if (deltaY !== 0) {
3035
+ await humanScroll(page, deltaY);
3036
+ }
3037
+ if (deltaX !== 0) {
3038
+ await page.mouse.wheel(deltaX, 0);
3039
+ }
3040
+ this.logger?.log("scroll", {
3041
+ ref,
3042
+ selector,
3043
+ label,
3044
+ deltaX,
3045
+ deltaY,
3046
+ });
3047
+ return `Scrolled ${label} by x=${deltaX}, y=${deltaY}`;
3048
+ }
2804
3049
  async wait(opts) {
2805
3050
  const page = await this.browser.getActivePage();
2806
3051
  const timeout = opts.timeoutMs || 10000;
@@ -2832,10 +3077,10 @@ export class BrowserActions {
2832
3077
  const norm = normalizeSelector(opts.selectorHidden);
2833
3078
  if (!norm.ok)
2834
3079
  return `Wait error: ${norm.error}`;
2835
- await page.locator(norm.selector).first().waitFor({
2836
- state: "hidden",
2837
- timeout,
2838
- });
3080
+ const result = await waitForNoVisibleMatches(page.locator(norm.selector), timeout);
3081
+ if (!result.ok) {
3082
+ return `Wait timeout: selector still visible: ${norm.selector} (${result.visibleCount}/${result.totalCount} visible)`;
3083
+ }
2839
3084
  this.logger?.log("wait", { selectorHidden: norm.selector });
2840
3085
  return `Selector hidden: ${norm.selector}`;
2841
3086
  }
@@ -2976,6 +3221,12 @@ export class BrowserActions {
2976
3221
  }
2977
3222
  async evaluate(script) {
2978
3223
  await this.interActionDelay();
3224
+ if (!this.allowEvaluateFallbacks()) {
3225
+ this.logger?.log("evaluate", { script, error: EVALUATE_FALLBACK_DISABLED }, false);
3226
+ return (`Error: ${EVALUATE_FALLBACK_DISABLED}. ` +
3227
+ `Use high-level browser actions such as click, type, scroll, wait, ` +
3228
+ `extractVisibleText, queryByText, findClickableNearText, or extractLinks.`);
3229
+ }
2979
3230
  const page = await this.browser.getActivePage();
2980
3231
  // Cheap syntactic sanity check via `new Function` — no DOM, no round-trip.
2981
3232
  // Production logs showed 7 evaluate syntax errors that Playwright