@testmuai/playwright-bindings 0.1.26 → 0.1.27

package/dist/helpers/coordinateResolverRead.js

@@ -0,0 +1,107 @@
+import { log } from '../log.js';
+// === CANONICAL_READ_RESOLVER_JS_START === (edit ALL trees together; spec §4.3)
+export const READ_RESOLVER_JS = `\
+try {
+  var el = document.elementFromPoint(x, y);
+  if (!el) { return null; }
+  while (el.shadowRoot) {
+    var deeper = el.shadowRoot.elementFromPoint(x, y);
+    if (!deeper || deeper === el) { break; }
+    el = deeper;
+  }
+  if (el.getRootNode && el.getRootNode() !== document) { return null; }
+  var hitTag = el.tagName ? el.tagName.toLowerCase() : '';
+  if (hitTag === 'iframe' || hitTag === 'frame' || hitTag === 'canvas' || hitTag === 'video' || hitTag === 'img') { return null; }
+
+  // *** NO interactable up-walk here (the ONLY structural difference from
+  // RESOLVER_JS): the read must stay on the exact direct hit so non-inherited
+  // CSS (background-color) is read off the correct box. ***
+
+  function xpathLiteral(v) {
+    if (v.indexOf("'") === -1) { return "'" + v + "'"; }
+    if (v.indexOf('"') === -1) { return '"' + v + '"'; }
+    return "concat('" + v.split("'").join("', \\"'\\", '") + "')";
+  }
+  function verifies(xp) {
+    try {
+      var r = document.evaluate(xp, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+      return r.snapshotLength === 1 && r.snapshotItem(0) === el;
+    } catch (e) { return false; }
+  }
+  var tag = el.tagName.toLowerCase();
+  var candidates = [];
+  if (el.id) { candidates.push('//*[@id=' + xpathLiteral(el.id) + ']'); }
+  var ATTRS = ['data-testid', 'data-test', 'data-qa', 'name', 'aria-label', 'placeholder', 'title'];
+  for (var i = 0; i < ATTRS.length; i++) {
+    var av = el.getAttribute(ATTRS[i]);
+    if (av) { candidates.push('//' + tag + '[@' + ATTRS[i] + '=' + xpathLiteral(av) + ']'); break; }
+  }
+  var text = (el.textContent || '').replace(/\\s+/g, ' ').trim();
+  if (text && text.length <= 64) {
+    candidates.push('//' + tag + '[normalize-space(.)=' + xpathLiteral(text) + ']');
+  }
+  var parts = [];
+  var node = el;
+  while (node && node.nodeType === 1) {
+    var name = node.tagName.toLowerCase();
+    var idx = 1;
+    var sib = node.previousElementSibling;
+    while (sib) { if (sib.tagName === node.tagName) { idx += 1; } sib = sib.previousElementSibling; }
+    parts.unshift(name + '[' + idx + ']');
+    node = node.parentElement;
+  }
+  candidates.push('/' + parts.join('/'));
+  for (var c = 0; c < candidates.length; c++) {
+    if (verifies(candidates[c])) {
+      return { xpath: candidates[c], tag: tag, id: el.id || '', text: text.slice(0, 80) };
+    }
+  }
+  return null;
+} catch (e) {
+  return null;
+}
+`;
+// === CANONICAL_READ_RESOLVER_JS_END ===
+// Built via the Function constructor (browser-executed by Playwright, which
+// serializes fn.toString() over the wire) — the grid CDP relay returns
+// undefined for STRING page-functions, so a plain string wrap never runs.
+// eslint-disable-next-line @typescript-eslint/no-implied-eval
+const WRAPPED_READ_FN = new Function('args', 'const [x, y] = args;\n' + READ_RESOLVER_JS);
+/**
+ * Resolve viewport-CSS (x, y) to a verified XPath for READING, or null.
+ *
+ * Identical no-throw contract to resolveCoordinate but uses READ_RESOLVER_JS
+ * (no interactable up-walk), so the derived xpath is the EXACT direct hit —
+ * correct for non-interactable nodes and non-inherited CSS (background-color).
+ *
+ * null ALWAYS means "use the server fallback" (shadow-DOM hit, iframe hit,
+ * canvas/video/img hit, no node, verification failure, or any JS error).
+ */
+export async function resolveCoordinateRead(page, x, y) {
+    let raw;
+    try {
+        raw = await page.evaluate(WRAPPED_READ_FN, [Math.trunc(x), Math.trunc(y)]);
+    }
+    catch (exc) {
+        log.helper(`    [read-resolver] derived_xpath=None reason=js-error: ${String(exc)}`);
+        return null;
+    }
+    if (raw === null || typeof raw !== 'object') {
+        log.helper('    [read-resolver] derived_xpath=None reason=no-node-or-bail');
+        return null;
+    }
+    const obj = raw;
+    const xpath = obj['xpath'];
+    if (typeof xpath !== 'string' || !xpath) {
+        log.helper('    [read-resolver] derived_xpath=None reason=verify-failed');
+        return null;
+    }
+    const meta = {
+        tag: String(obj['tag'] ?? ''),
+        id: String(obj['id'] ?? ''),
+        text: String(obj['text'] ?? ''),
+    };
+    log.helper(`    [read-resolver] derived_xpath=${xpath} meta=${JSON.stringify(meta)}`);
+    return { xpath, meta };
+}
+//# sourceMappingURL=coordinateResolverRead.js.map

package/dist/helpers/coordinateResolverRead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinateResolverRead.js","sourceRoot":"","sources":["../../src/helpers/coordinateResolverRead.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4D/B,CAAC;AACF,yCAAyC;AAEzC,4EAA4E;AAC5E,uEAAuE;AACvE,0EAA0E;AAC1E,8DAA8D;AAC9D,MAAM,eAAe,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,wBAAwB,GAAG,gBAAgB,CAE5E,CAAC;AAQb;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,IAAU,EACV,CAAS,EACT,CAAS;IAET,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,eAAwB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAU,CAAC,CAAC;IAC/F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,MAAM,CAAC,2DAA2D,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,GAAG,CAAC,MAAM,CAAC,+DAA+D,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,EAAE,CAAC;QACxC,GAAG,CAAC,MAAM,CAAC,6DAA6D,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG;QACX,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;KAChC,CAAC;IACF,GAAG,CAAC,MAAM,CAAC,qCAAqC,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtF,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/helpers/dialog.d.ts

@@ -0,0 +1,29 @@
+/**
+ * V3 JS-dialog handling — prime a persistent accept/dismiss policy.
+ *
+ * Playwright auto-dismisses a JavaScript dialog (alert / confirm / prompt)
+ * unless a `page.on('dialog')` listener is registered BEFORE the action that
+ * opens it. The generator records the dialog-response operation AFTER the
+ * triggering action (instruction N = trigger, N+1 = JS_DIALOG — the Selenium
+ * post-hoc order), so a Selenium-style `switch_to.alert` is impossible here:
+ * by the time the JS_DIALOG op runs the dialog is already gone.
+ *
+ * The fix is a permanent handler primed up front. `primeDialog` registers ONE
+ * idempotent, page-scoped listener and mutates a per-page policy the listener
+ * consults for every dialog.
+ */
+import type { Page } from 'playwright';
+/**
+ * Arm/refresh the JS-dialog policy for `page` and ensure a live listener.
+ *
+ * Idempotent per page: the listener is registered exactly once; later calls
+ * only update the policy applied to every future dialog.
+ *
+ * Async so generated code can `await` it uniformly with the other page
+ * helpers; it performs no I/O itself.
+ */
+export declare function primeDialog(page: Page, opts?: {
+    action?: string;
+    value?: string;
+}): Promise<void>;
+//# sourceMappingURL=dialog.d.ts.map

package/dist/helpers/dialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog.d.ts","sourceRoot":"","sources":["../../src/helpers/dialog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAU,IAAI,EAAE,MAAM,YAAY,CAAC;AAa/C;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,IAAI,CAAC,CAsBf"}

package/dist/helpers/dialog.js

@@ -0,0 +1,35 @@
+const DEFAULT_POLICY = { action: 'dismiss', value: '' };
+// Keyed weakly so a closed/GC'd page auto-evicts.
+const policies = new WeakMap();
+const registered = new WeakMap();
+/**
+ * Arm/refresh the JS-dialog policy for `page` and ensure a live listener.
+ *
+ * Idempotent per page: the listener is registered exactly once; later calls
+ * only update the policy applied to every future dialog.
+ *
+ * Async so generated code can `await` it uniformly with the other page
+ * helpers; it performs no I/O itself.
+ */
+export async function primeDialog(page, opts = {}) {
+    policies.set(page, {
+        action: (opts.action || 'dismiss').trim().toLowerCase(),
+        value: opts.value || '',
+    });
+    if (registered.get(page))
+        return;
+    page.on('dialog', (dialog) => {
+        const policy = policies.get(page) ?? DEFAULT_POLICY;
+        const settled = policy.action === 'accept'
+            ? policy.value
+                ? dialog.accept(policy.value)
+                : dialog.accept()
+            : dialog.dismiss();
+        // The listener is sync but accept()/dismiss() are async. Swallow rejection
+        // rather than let it float: an unhandled rejection kills the Node process
+        // before the LT status is reported, surfacing as "completed" on the grid.
+        void settled.catch(() => { });
+    });
+    registered.set(page, true);
+}
+//# sourceMappingURL=dialog.js.map

package/dist/helpers/dialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialog.js","sourceRoot":"","sources":["../../src/helpers/dialog.ts"],"names":[],"mappings":"AAqBA,MAAM,cAAc,GAAiB,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAEtE,kDAAkD;AAClD,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAsB,CAAC;AACnD,MAAM,UAAU,GAAG,IAAI,OAAO,EAAiB,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAU,EACV,OAA4C,EAAE;IAE9C,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE;QACjB,MAAM,EAAE,CAAC,IAAI,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE;QACvD,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE;KACxB,CAAC,CAAC;IAEH,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IAEjC,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAc,EAAE,EAAE;QACnC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC;QACpD,MAAM,OAAO,GACX,MAAM,CAAC,MAAM,KAAK,QAAQ;YACxB,CAAC,CAAC,MAAM,CAAC,KAAK;gBACZ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC7B,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE;YACnB,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,2EAA2E;QAC3E,0EAA0E;QAC1E,0EAA0E;QAC1E,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAA+C,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;IACH,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/helpers/drag.d.ts

@@ -1,3 +1,38 @@
-import type { Page } from 'playwright';
+/**
+ * Drag helpers — PY _helpers/drag.py port. clickDrag is the legacy V4
+ * coordinate drag; dragDrop / elementDrag add the V3-gated heal path
+ * (DESKTOP_LOCATE on endpoint-lookup miss, derived-xpath verify, same-round
+ * coordinate fallback, fallback_coordinates as true last resort).
+ */
+import type { ElementHandle, Locator, Page } from 'playwright';
+import type { SelectorSpec } from '../visionLocator.js';
+type Endpoint = Locator | ElementHandle | SelectorSpec[];
+type XY = [number, number];
 export declare function clickDrag(page: Page, x1: number, y1: number, x2: number, y2: number, steps?: number): Promise<void>;
+export interface DragDropOptions {
+    sourceDescription?: string;
+    targetDescription?: string;
+    fallbackCoordinates?: [XY, XY] | null;
+    autoheal?: boolean;
+    maxAttempts?: number;
+    retryDelayMs?: number;
+}
+/**
+ * Drag source onto target with the V2 gesture; heal selector-list endpoints.
+ * Locator/handle pair → element gesture (heal opts ignored on this shape).
+ */
+export declare function dragDrop(page: Page, source: Endpoint, target: Endpoint, opts?: DragDropOptions): Promise<boolean | undefined>;
+export interface ElementDragOptions {
+    description?: string;
+    fallbackCoordinates?: XY | null;
+    autoheal?: boolean;
+    maxAttempts?: number;
+    retryDelayMs?: number;
+}
+/**
+ * Heal-capable relative element drag. Locator/handle source → centre to
+ * centre+(dx,dy); selector-list source → V3-gated heal path.
+ */
+export declare function elementDrag(page: Page, source: Endpoint, dx: number, dy: number, opts?: ElementDragOptions): Promise<boolean>;
+export {};
 //# sourceMappingURL=drag.d.ts.map

package/dist/helpers/drag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drag.d.ts","sourceRoot":"","sources":["../../src/helpers/drag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGvC,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrH"}
+{"version":3,"file":"drag.d.ts","sourceRoot":"","sources":["../../src/helpers/drag.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAK/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAcxD,KAAK,QAAQ,GAAG,OAAO,GAAG,aAAa,GAAG,YAAY,EAAE,CAAC;AACzD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE3B,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrH;AA0JD,MAAM,WAAW,eAAe;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,QAAQ,EAChB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CA+C9B;AAsBD,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,QAAQ,EAChB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,OAAO,CAAC,CA+ClB"}

package/dist/helpers/drag.js

@@ -1,4 +1,17 @@
+import { AutohealExhausted } from '../errors.js';
+import { get as configGet, isV3 } from '../configure.js';
+import { getV3DesktopLocateTarget } from './healCascade.js';
+import { resolveCoordinate } from './coordinateResolver.js';
 import { log } from '../log.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// V2-parity constants (not parameterized in V2).
+const DROP_ZONE_NUDGE_X = 0.1;
+const DROP_ZONE_NUDGE_Y = 0.1;
+const COORD_GESTURE_PAUSE_MS = 100;
+const DRAG_STEPS = 20;
+// Cap the derived-xpath re-lookup so a stale selector fails fast to the same
+// round's coordinates instead of burning the full action timeout.
+const DERIVED_LOOKUP_CAP_MS = 5000;
 export async function clickDrag(page, x1, y1, x2, y2, steps = 20) {
     log.helper(`[click_drag] from=(${x1},${y1}) to=(${x2},${y2}) steps=${steps}`);
     await page.mouse.move(x1, y1);
@@ -6,4 +19,258 @@ export async function clickDrag(page, x1, y1, x2, y2, steps = 20) {
     await page.mouse.move(x2, y2, { steps });
     await page.mouse.up();
 }
+/** Internal control-flow marker: DESKTOP_LOCATE missed for an endpoint. */
+class LocateMiss extends Error {
+    original;
+    constructor(original) {
+        super('DESKTOP_LOCATE miss');
+        this.name = 'LocateMiss';
+        this.original = original;
+    }
+}
+function isRecoverable(e) {
+    return e?.name === 'TimeoutError';
+}
+function buildLocator(page, selectorList) {
+    const sel = selectorList[0];
+    const raw = sel.selector ?? '';
+    return sel.isXPath ? page.locator(`xpath=${raw}`) : page.locator(raw);
+}
+function lookupTimeoutMs() {
+    return Number(configGet('defaultActionTimeoutMs') ?? 0) || 10000;
+}
+async function viewport(page) {
+    const dims = (await page.evaluate(() => [window.innerWidth, window.innerHeight]));
+    return [Math.trunc(dims[0] ?? 0), Math.trunc(dims[1] ?? 0)];
+}
+/** Element endpoint → viewport-CSS rect centre, clamped. A missing box throws
+ * a TimeoutError-named error so the attempt loop can retry. */
+async function elementCenter(page, locator) {
+    const box = await locator.boundingBox();
+    if (!box) {
+        const e = new Error('element has no bounding box (not visible/attached)');
+        e.name = 'TimeoutError';
+        throw e;
+    }
+    const cx = box.x + box.width / 2;
+    const cy = box.y + box.height / 2;
+    const [vw, vh] = await viewport(page);
+    return [
+        Math.max(0, Math.min(Math.trunc(cx), vw - 1)),
+        Math.max(0, Math.min(Math.trunc(cy), vh - 1)),
+    ];
+}
+/** V2 element drag: press at source, travel, (0.1, 0.1) nudge at the drop
+ * zone to activate the droppable, release. */
+async function elementGesture(page, [sx, sy], [tx, ty]) {
+    await page.mouse.move(sx, sy);
+    await page.mouse.down();
+    await page.mouse.move(tx, ty, { steps: DRAG_STEPS });
+    await page.mouse.move(tx + DROP_ZONE_NUDGE_X, ty + DROP_ZONE_NUDGE_Y);
+    await page.mouse.up();
+    return true;
+}
+/** V2 coordinate drag: press at src, settle, travel, settle, release. */
+async function coordinateGesture(page, [sx, sy], [tx, ty]) {
+    await page.mouse.move(sx, sy);
+    await page.mouse.down();
+    await sleep(COORD_GESTURE_PAUSE_MS);
+    await page.mouse.move(tx, ty, { steps: DRAG_STEPS });
+    await sleep(COORD_GESTURE_PAUSE_MS);
+    await page.mouse.up();
+    return true;
+}
+/** Both endpoints elements → centres first (a stale endpoint fails BEFORE any
+ * mouse press), then the V2 element gesture. */
+async function elementPairGesture(page, source, target) {
+    const srcC = await elementCenter(page, source);
+    const tgtC = await elementCenter(page, target);
+    return elementGesture(page, srcC, tgtC);
+}
+/** Resolve one endpoint → { loc | xy } + this round's fresh heal coords (the
+ * caller stashes them so the next attempt skips locate). Throws LocateMiss on
+ * a locate miss; the original lookup error when heal is unavailable. */
+async function resolveEndpoint(page, endpoint, description, opts) {
+    if (opts.stashedCoords !== null)
+        return [{ loc: null, xy: opts.stashedCoords }, null];
+    if (!Array.isArray(endpoint))
+        return [{ loc: endpoint, xy: null }, null];
+    let lookupExc;
+    try {
+        if (!endpoint.length) {
+            const e = new Error('empty selector list');
+            e.name = 'TimeoutError';
+            throw e;
+        }
+        const locator = buildLocator(page, endpoint);
+        await locator.waitFor({ state: 'visible', timeout: lookupTimeoutMs() });
+        return [{ loc: locator, xy: null }, null];
+    }
+    catch (e) {
+        if (!isRecoverable(e))
+            throw e;
+        lookupExc = e;
+    }
+    // Heal is V3-only; v4 (or autoheal off) propagates without a locate call.
+    if (!opts.autoheal || !isV3())
+        throw lookupExc;
+    const label = opts.isTarget ? 'target' : 'source';
+    log.helper(`[${opts.verbName}] ${label} endpoint lookup failed; DESKTOP_LOCATE drop_aware=${opts.isTarget}`);
+    const coords = await getV3DesktopLocateTarget(page, description, opts.verbName, {
+        dropAware: opts.isTarget,
+    });
+    if (coords === null)
+        throw new LocateMiss(lookupExc);
+    const [vx, vy] = coords;
+    const resolved = await resolveCoordinate(page, vx, vy);
+    if (resolved !== null) {
+        try {
+            const derived = page.locator(`xpath=${resolved.xpath}`);
+            await derived.waitFor({
+                state: 'visible',
+                timeout: Math.min(lookupTimeoutMs(), DERIVED_LOOKUP_CAP_MS),
+            });
+            return [{ loc: derived, xy: null }, [vx, vy]];
+        }
+        catch (e) {
+            if (!isRecoverable(e))
+                throw e;
+            // Derived xpath unfindable — same round's coordinates carry the gesture.
+        }
+    }
+    return [{ loc: null, xy: [vx, vy] }, [vx, vy]];
+}
+/** Exhaustion: the stored pair is dispatched exactly once (its own failure
+ * propagates), else AutohealExhausted. */
+async function exhaust(page, fallbackCoordinates, original) {
+    if (fallbackCoordinates !== null) {
+        const [srcXy, tgtXy] = fallbackCoordinates;
+        log.helper(`[drag_drop] heal exhausted; recorded fallback_coordinates ${JSON.stringify(srcXy)} -> ${JSON.stringify(tgtXy)}`);
+        return coordinateGesture(page, srcXy, tgtXy);
+    }
+    const err = new AutohealExhausted('drag_drop heal cascade exhausted');
+    err.cause = original;
+    throw err;
+}
+/**
+ * Drag source onto target with the V2 gesture; heal selector-list endpoints.
+ * Locator/handle pair → element gesture (heal opts ignored on this shape).
+ */
+export async function dragDrop(page, source, target, opts = {}) {
+    const { sourceDescription = '', targetDescription = '', fallbackCoordinates = null, autoheal = true, maxAttempts = 3, retryDelayMs = 500, } = opts;
+    if (!Array.isArray(source) && !Array.isArray(target)) {
+        await elementPairGesture(page, source, target);
+        return undefined;
+    }
+    let firstExc = null;
+    // Per-endpoint fresh-coords stash: [source, target].
+    const stash = [null, null];
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        log.helper(`[drag_drop] is_retry: ${attempt > 0}`);
+        let src, tgt;
+        try {
+            [src, stash[0]] = await resolveEndpoint(page, source, sourceDescription, {
+                isTarget: false, autoheal, stashedCoords: stash[0], verbName: 'drag_drop',
+            });
+            [tgt, stash[1]] = await resolveEndpoint(page, target, targetDescription, {
+                isTarget: true, autoheal, stashedCoords: stash[1], verbName: 'drag_drop',
+            });
+        }
+        catch (e) {
+            if (e?.name === 'LocateMiss') {
+                return exhaust(page, fallbackCoordinates, firstExc ?? e.original);
+            }
+            throw e;
+        }
+        try {
+            if (src.loc !== null && tgt.loc !== null) {
+                return await elementPairGesture(page, src.loc, tgt.loc);
+            }
+            const srcXy = src.xy ?? (await elementCenter(page, src.loc));
+            const tgtXy = tgt.xy ?? (await elementCenter(page, tgt.loc));
+            log.helper(`[drag_drop] coordinate gesture ${JSON.stringify(srcXy)} -> ${JSON.stringify(tgtXy)}`);
+            return await coordinateGesture(page, srcXy, tgtXy);
+        }
+        catch (e) {
+            if (!isRecoverable(e))
+                throw e;
+            if (firstExc === null)
+                firstExc = e;
+            if (!autoheal)
+                throw e;
+            if (attempt === maxAttempts - 1)
+                return exhaust(page, fallbackCoordinates, firstExc);
+            log.helper(`[drag_drop] retry ${attempt + 1}/${maxAttempts} after ${e.name}`);
+            await sleep(retryDelayMs);
+        }
+    }
+    return undefined;
+}
+async function elementDragExhaust(page, dx, dy, fallbackCoordinates, original) {
+    if (fallbackCoordinates !== null) {
+        const [fx, fy] = fallbackCoordinates;
+        const [vw, vh] = await viewport(page);
+        const ex = Math.max(0, Math.min(Math.trunc(fx + dx), vw - 1));
+        const ey = Math.max(0, Math.min(Math.trunc(fy + dy), vh - 1));
+        log.helper(`[element_drag] heal exhausted; recorded fallback (${fx}, ${fy}) -> (${ex}, ${ey})`);
+        return coordinateGesture(page, [fx, fy], [ex, ey]);
+    }
+    const err = new AutohealExhausted('element_drag heal cascade exhausted');
+    err.cause = original;
+    throw err;
+}
+/**
+ * Heal-capable relative element drag. Locator/handle source → centre to
+ * centre+(dx,dy); selector-list source → V3-gated heal path.
+ */
+export async function elementDrag(page, source, dx, dy, opts = {}) {
+    const { description = '', fallbackCoordinates = null, autoheal = true, maxAttempts = 4, retryDelayMs = 500, } = opts;
+    if (!Array.isArray(source)) {
+        const [cx, cy] = await elementCenter(page, source);
+        log.helper(`[element_drag] element centre (${cx}, ${cy}) dx=${dx} dy=${dy}`);
+        return coordinateGesture(page, [cx, cy], [cx + dx, cy + dy]);
+    }
+    let firstExc = null;
+    let stash = null;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        log.helper(`[element_drag] is_retry: ${attempt > 0}`);
+        let origin, fresh;
+        try {
+            [origin, fresh] = await resolveEndpoint(page, source, description, {
+                isTarget: false, autoheal, stashedCoords: stash, verbName: 'element_drag',
+            });
+        }
+        catch (e) {
+            if (e?.name === 'LocateMiss') {
+                return elementDragExhaust(page, dx, dy, fallbackCoordinates, firstExc ?? e.original);
+            }
+            throw e;
+        }
+        stash = fresh;
+        try {
+            const [ox, oy] = origin.xy ?? (await elementCenter(page, origin.loc));
+            const [vw, vh] = await viewport(page);
+            const ex = Math.max(0, Math.min(Math.trunc(ox + dx), vw - 1));
+            const ey = Math.max(0, Math.min(Math.trunc(oy + dy), vh - 1));
+            log.helper(`[element_drag] origin (${ox}, ${oy}) -> end (${ex}, ${ey})`);
+            return await coordinateGesture(page, [ox, oy], [ex, ey]);
+        }
+        catch (e) {
+            if (!isRecoverable(e))
+                throw e;
+            if (firstExc === null)
+                firstExc = e;
+            if (!autoheal)
+                throw e;
+            if (attempt === maxAttempts - 1) {
+                return elementDragExhaust(page, dx, dy, fallbackCoordinates, firstExc);
+            }
+            log.helper(`[element_drag] retry ${attempt + 1}/${maxAttempts} after ${e.name}`);
+            await sleep(retryDelayMs);
+        }
+    }
+    const err = new AutohealExhausted('element_drag attempt loop exhausted');
+    err.cause = firstExc;
+    throw err;
+}
 //# sourceMappingURL=drag.js.map

package/dist/helpers/drag.js.map

@@ -1 +1 @@
-{"version":3,"file":"drag.js","sourceRoot":"","sources":["../../src/helpers/drag.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAU,EAAE,EAAU,EAAE,EAAU,EAAE,EAAU,EAAE,EAAU,EAAE,KAAK,GAAG,EAAE;IACpG,GAAG,CAAC,MAAM,CAAC,sBAAsB,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,KAAK,EAAE,CAAC,CAAC;IAC9E,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9B,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACxB,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACzC,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;AACxB,CAAC"}
+{"version":3,"file":"drag.js","sourceRoot":"","sources":["../../src/helpers/drag.ts"],"names":[],"mappings":"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"}

package/dist/helpers/executeApi.d.ts

@@ -47,6 +47,8 @@ export interface ApiResponse {
     response_body: unknown;
     body: string;
     time: number;
+    /** Set only on the V3 fail-open soft result. */
+    message?: string;
 }
 export declare function executeApi(req: ApiRequest): Promise<ApiResponse>;
 //# sourceMappingURL=executeApi.d.ts.map

package/dist/helpers/executeApi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executeApi.d.ts","sourceRoot":"","sources":["../../src/helpers/executeApi.ts"],"names":[],"mappings":"AAwBA,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAc9D;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAM5F;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,SAAS,GAAG,MAAM,CAQhE;AAGD,MAAM,WAAW,UAAU;IAAG,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAAE;AACxE,MAAM,WAAW,SAAS;IAAI,IAAI,EAAE,OAAO,CAAC;IAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAAE;AAC9F,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;KAC/B,CAAC;CACH;AACD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,gBAAgB,GAAG,MAAM,CAAC;AAE/E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,QAAQ,CAAC,EAAE;QAAE,6BAA6B,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAID,wBAAsB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAsLtE"}
+{"version":3,"file":"executeApi.d.ts","sourceRoot":"","sources":["../../src/helpers/executeApi.ts"],"names":[],"mappings":"AAyBA,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAc9D;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAM5F;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,SAAS,GAAG,MAAM,CAQhE;AAGD,MAAM,WAAW,UAAU;IAAG,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAAE;AACxE,MAAM,WAAW,SAAS;IAAI,IAAI,EAAE,OAAO,CAAC;IAAE,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAAE;AAC9F,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;KAC/B,CAAC;CACH;AACD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,gBAAgB,GAAG,MAAM,CAAC;AAE/E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;IACzC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,QAAQ,CAAC,EAAE;QAAE,6BAA6B,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,aAAa,EAAE,OAAO,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,wBAAsB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAwMtE"}

package/dist/helpers/executeApi.js

@@ -1,5 +1,6 @@
 import { resolveVar } from '../vars.js';
 import { getApiProxyUrl } from '../config.js';
+import { isV3 } from '../configure.js';
 import { log, preview } from '../log.js';
 import { recordApiCall } from './apiCalls.js';
 // Header names that commonly carry credentials — masked before logging.
@@ -184,16 +185,35 @@ export async function executeApi(req) {
     const { httpRequest } = await import('../httpClient.js');
     log.helper(`[execute_api] headers=${preview(JSON.stringify(redactHeadersForLog(headers)), 200)}`);
     const started = Date.now();
-    const resp = await httpRequest({
-        method: req.method,
-        url: url.toString(),
-        headers,
-        body,
-        proxyUrl,
-        verify,
-        timeoutMs: timeout,
-        followRedirects: req.settings?.automatically_follow_redirect !== false,
-    });
+    let resp;
+    try {
+        resp = await httpRequest({
+            method: req.method,
+            url: url.toString(),
+            headers,
+            body,
+            proxyUrl,
+            verify,
+            timeoutMs: timeout,
+            followRedirects: req.settings?.automatically_follow_redirect !== false,
+        });
+    }
+    catch (e) {
+        // V3 fails OPEN on a request failure (network error, proxy/connect stall,
+        // timeout): a soft {status:400} lets the author's own status assertion
+        // decide. Input-validation errors above still propagate. V4 unchanged.
+        if (isV3()) {
+            log.helper(`[execute_api] request failed (v3 fail-open): ${String(e)}`);
+            return {
+                status: 400, headers: {}, cookies: {},
+                response_body: `API request failed ${String(e)}`,
+                body: `API request failed ${String(e)}`,
+                time: Date.now() - started,
+                message: `API request failed ${String(e)}`,
+            };
+        }
+        throw e;
+    }
     const elapsed = Date.now() - started;
     log.helper(`[execute_api] status=${resp.status} time=${elapsed}ms`);
     const respHeaders = {};