@testmuai/playwright-bindings 0.1.26 → 0.1.27-beta.1

package/dist/actionEngine.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Find → act → heal loop for Playwright verbs — port of PY _action_engine.py.
+ *
+ * Entry: runVerb(page, locator, spec, args, opts). Callers:
+ *  - VisionLocator methods (empty-selector vision-agent ops; locator=null)
+ *  - the Locator heal-patch V3 delegation (locator = the original)
+ *
+ * Per attempt: (1) try the runner on the locator; recoverable failure falls
+ * to (2) the heal cascade (per-verb tiers); (3) selectorXpath → rebuild
+ * locator and retry, keeping coordinates as the in-round fallback; (4)
+ * coordinates-only → coordRunner. The final attempt propagates its own
+ * failure (PY :245); a full-cascade miss propagates AutohealExhausted
+ * (honouring codegen fallback_coordinates first, spec §3.4).
+ */
+import type { Locator, Page } from 'playwright';
+import { type VerbSpec } from './actionSpecs.js';
+export declare function inEngine(): boolean;
+/** Pin the right Playwright engine for a heal-derived selector: an absolute
+ * xpath ('/html[1]/...') or union '(//a|//b)[1]' parses as CSS and throws
+ * unless prefixed; engine-pinned and genuine CSS pass through. */
+export declare function engineSelector(selector: string): string;
+export interface RunVerbOptions {
+    description: string;
+    verbName: string;
+    autoheal?: boolean;
+    maxAttempts?: number;
+    retryDelayMs?: number;
+    /** Authoring-time coords persisted by codegen for selectorless ops —
+     * consumed ONLY when the cascade exhausts (spec §3.4). */
+    fallbackCoordinates?: [number, number] | null;
+}
+/**
+ * Execute the verb spec on the locator (or via heal when locator is null),
+ * retrying with the heal cascade on recoverable failures.
+ */
+export declare function runVerb(page: Page, locator: Locator | null, spec: VerbSpec, args: unknown[], opts: RunVerbOptions): Promise<unknown>;
+//# sourceMappingURL=actionEngine.d.ts.map

package/dist/actionEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionEngine.d.ts","sourceRoot":"","sources":["../src/actionEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGhD,OAAO,EAA6B,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAU5E,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AA8CD;;kEAEkE;AAClE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;8DAC0D;IAC1D,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,OAAO,EAAE,EACf,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,OAAO,CAAC,CAQlB"}

package/dist/actionEngine.js

@@ -0,0 +1,194 @@
+import { AutohealExhausted } from './errors.js';
+import { healCascade } from './helpers/healCascade.js';
+import { DEFAULT_RECOVERABLE_NAMES } from './actionSpecs.js';
+import { log } from './log.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Re-entry guard: set while the engine drives Locator methods so the heal
+// patch's wrapper passes calls straight through instead of re-entering the
+// cascade. Module-level is correct — session.run() executes tests
+// sequentially (see the contract's runtime-conventions block).
+let _inEngine = false;
+export function inEngine() {
+    return _inEngine;
+}
+/** Recoverable = heal-triggering. Match by `.name` (contract rule — a nested
+ * playwright install makes instanceof silently false) plus Playwright's
+ * strict-mode violation, which is a plain Error with a message signature. */
+function isRecoverable(e, names) {
+    const err = e;
+    if (!err)
+        return false;
+    if (names.includes(err.name))
+        return true;
+    return typeof err.message === 'string' && err.message.includes('strict mode violation');
+}
+/** Recover the owning Page when codegen hands a frame/shadow scope where a
+ * Page is required (screenshots, page.mouse, isClosed). Locator → .page();
+ * FrameLocator → .owner().page(). Fall back to the original so the caller's
+ * error surfaces unchanged. */
+function coerceToPage(page) {
+    const p = page;
+    if (typeof p['isClosed'] === 'function')
+        return page;
+    try {
+        if (typeof p['page'] === 'function') {
+            const rec = p['page']();
+            if (rec && typeof rec['isClosed'] === 'function')
+                return rec;
+        }
+        if (typeof p['owner'] === 'function') {
+            const owner = p['owner']();
+            if (owner && typeof owner['page'] === 'function') {
+                const rec = owner['page']();
+                if (rec && typeof rec['isClosed'] === 'function')
+                    return rec;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return page;
+}
+/** A Playwright action error: TimeoutError, or a plain Error whose message
+ * carries the locator-method prefix / strict-mode signature. Matched by shape
+ * (never instanceof — nested playwright installs). */
+function isPlaywrightActionError(e) {
+    const err = e;
+    if (!err || typeof err.message !== 'string')
+        return false;
+    if (err.name === 'TimeoutError')
+        return true;
+    if (err.name !== 'Error')
+        return false;
+    return /^\s*locator\.\w+/i.test(err.message) || err.message.includes('strict mode violation');
+}
+/** Pin the right Playwright engine for a heal-derived selector: an absolute
+ * xpath ('/html[1]/...') or union '(//a|//b)[1]' parses as CSS and throws
+ * unless prefixed; engine-pinned and genuine CSS pass through. */
+export function engineSelector(selector) {
+    if (selector.startsWith('xpath=') || selector.startsWith('css='))
+        return selector;
+    if (selector.startsWith('/') || selector.startsWith('('))
+        return `xpath=${selector}`;
+    return selector;
+}
+/**
+ * Execute the verb spec on the locator (or via heal when locator is null),
+ * retrying with the heal cascade on recoverable failures.
+ */
+export async function runVerb(page, locator, spec, args, opts) {
+    const prevGuard = _inEngine;
+    _inEngine = true;
+    try {
+        return await runVerbInner(page, locator, spec, args, opts);
+    }
+    finally {
+        _inEngine = prevGuard;
+    }
+}
+async function runVerbInner(pageIn, locatorIn, spec, args, opts) {
+    const { description, verbName, autoheal = true, maxAttempts = 4, retryDelayMs = 500, fallbackCoordinates = null, } = opts;
+    const recoverable = spec.recoverableNames ?? DEFAULT_RECOVERABLE_NAMES;
+    let page = coerceToPage(pageIn);
+    let locator = locatorIn;
+    let firstExc = null;
+    // Stash for a heal round that returned BOTH selector and coordinates: when
+    // the xpath attempt fails, fall back to the same round's coordinates
+    // without a second cascade call (spec §3.3).
+    let pendingCoordFallback = null;
+    // Dead-page guard: re-point to the most-recent surviving page (Selenium
+    // dead-window heal parity) and null the stale locator.
+    if (page.isClosed()) {
+        const ctxPages = page.context().pages();
+        if (!ctxPages.length) {
+            throw new Error(`all pages are closed; cannot perform '${verbName}' on '${description}'`);
+        }
+        page = ctxPages[ctxPages.length - 1];
+        await page.bringToFront();
+        locator = null;
+    }
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        // Step 1 — try the verb on the current locator.
+        if (locator !== null) {
+            try {
+                return await spec.runner(locator, ...args);
+            }
+            catch (exc) {
+                // A Playwright ACTION error on a heal-derived selector (e.g. the
+                // resolver up-walked to a label -> 'Element is not an <input>') is a
+                // wrong-element symptom, not a fatal: the same round's coordinates
+                // still carry the verb (keyboard input works on any focusable).
+                if (pendingCoordFallback !== null && spec.coordRunner &&
+                    isPlaywrightActionError(exc)) {
+                    const [fx, fy] = pendingCoordFallback;
+                    log.helper(`[engine] healed-selector action failed (${exc?.message?.slice(0, 60)}); coordinate fallback (${fx}, ${fy}) for ${verbName}`);
+                    return await spec.coordRunner(page, fx, fy, ...args);
+                }
+                // Heal-triggering: the verb's recoverable set (timeouts/strict-mode)
+                // PLUS any Playwright ACTION error — an authored selector resolving to
+                // the WRONG element (e.g. the search <form> instead of its input)
+                // raises 'Element is not an <input>...' on the FIRST attempt, and the
+                // cascade can re-find the true target by description (grid-proven:
+                // bing sb_form fill). Non-Playwright errors still propagate untouched.
+                if (!isRecoverable(exc, recoverable) && !isPlaywrightActionError(exc))
+                    throw exc;
+                if (firstExc === null)
+                    firstExc = exc;
+                if (!autoheal)
+                    throw exc;
+                // In-round coordinate fallback — checked BEFORE the final-attempt
+                // raise (Selenium parity: the stash fires even on the last attempt).
+                if (pendingCoordFallback !== null && spec.coordRunner) {
+                    const [x, y] = pendingCoordFallback;
+                    log.helper(`[engine] derived-xpath attempt failed (${exc?.name}); coordinate fallback (${x}, ${y}) for ${verbName}`);
+                    return await spec.coordRunner(page, x, y, ...args);
+                }
+                if (attempt === maxAttempts - 1)
+                    throw exc;
+            }
+        }
+        else if (!autoheal) {
+            throw new AutohealExhausted(`no locator and autoheal disabled for '${description}' (${verbName})`);
+        }
+        // Step 2 — heal cascade (fallback_coordinates honoured on exhaustion).
+        let heal;
+        try {
+            heal = await healCascade({
+                page, description, verbName,
+                ...(spec.tiers ? { tiers: spec.tiers } : {}),
+                lastException: firstExc,
+            });
+        }
+        catch (healExc) {
+            if (healExc?.name === 'AutohealExhausted' &&
+                fallbackCoordinates !== null && spec.coordRunner) {
+                const [x, y] = fallbackCoordinates;
+                log.helper(`[engine] cascade exhausted; recorded fallback_coordinates (${x}, ${y}) for ${verbName}`);
+                return await spec.coordRunner(page, x, y, ...args);
+            }
+            throw healExc;
+        }
+        // Step 3 — selector-first dispatch.
+        if (heal.selectorXpath != null) {
+            locator = page.locator(engineSelector(heal.selectorXpath));
+            pendingCoordFallback = heal.coordinates ?? null; // fresh supersedes stale
+            log.helper(`[engine] heal via ${heal.tierUsed} -> selector ${JSON.stringify(heal.selectorXpath)}, retrying ${verbName}`);
+            if (retryDelayMs > 0)
+                await sleep(retryDelayMs);
+            continue;
+        }
+        if (heal.coordinates != null) {
+            pendingCoordFallback = null;
+            if (!spec.coordRunner) {
+                throw new Error(`heal cascade resolved to coordinates ${JSON.stringify(heal.coordinates)} via tier '${heal.tierUsed}', but verb '${verbName}' has no coordRunner. Provide one on the VerbSpec or drop the coordinate tier.`);
+            }
+            const [x, y] = heal.coordinates;
+            log.helper(`[engine] heal via ${heal.tierUsed} -> coordRunner at (${x}, ${y}) for ${verbName}`);
+            return await spec.coordRunner(page, x, y, ...args);
+        }
+        throw new AutohealExhausted(`heal tier=${heal.tierUsed} returned no selector or coordinates for '${description}' (${verbName})`);
+    }
+    if (firstExc !== null)
+        throw firstExc;
+    throw new AutohealExhausted(`max_attempts=${maxAttempts} exhausted for '${description}' (${verbName})`);
+}
+//# sourceMappingURL=actionEngine.js.map

package/dist/actionEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionEngine.js","sourceRoot":"","sources":["../src/actionEngine.ts"],"names":[],"mappings":"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"}

package/dist/actionSpecs.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Per-verb runner/coord_runner specs for the V3 find→act→heal loop.
+ * Port of PY _action_specs.py. Coord runners click at the healed coordinate
+ * first to focus the field, then drive the keyboard (Selenium ActionBuilder
+ * dance adapted to Playwright's mouse + keyboard APIs).
+ */
+import type { ElementHandle, Locator, Page } from 'playwright';
+export type VerbKwargs = Record<string, unknown>;
+export type Runner = (locator: Locator, ...args: unknown[]) => Promise<unknown>;
+export type CoordRunner = (page: Page, x: number, y: number, ...args: unknown[]) => Promise<unknown>;
+/** Per-verb behaviour for the find→act→heal loop. `recoverableNames` are the
+ * error `.name`s that trigger heal (the contract's .name rule — instanceof is
+ * unsafe across nested playwright installs). `tiers` overrides the cascade. */
+export interface VerbSpec {
+    runner: Runner;
+    coordRunner?: CoordRunner;
+    recoverableNames?: readonly string[];
+    tiers?: readonly string[];
+}
+export declare const DEFAULT_RECOVERABLE_NAMES: readonly string[];
+export declare const CLICK_SPEC: VerbSpec;
+export declare const DBLCLICK_SPEC: VerbSpec;
+export declare const HOVER_SPEC: VerbSpec;
+export declare const LONG_PRESS_SPEC: VerbSpec;
+export declare const MULTI_CLICK_SPEC: VerbSpec;
+export declare const CLEAR_SPEC: VerbSpec;
+export declare const FILL_SPEC: VerbSpec;
+export declare const TYPE_SPEC: VerbSpec;
+export declare const PRESS_SPEC: VerbSpec;
+/** First <input type=file> via pure DOM (light + open shadow). Never raises. */
+export declare function resolveFileInputDom(page: Page): Promise<ElementHandle | null>;
+export declare const SET_INPUT_FILES_SPEC: VerbSpec;
+export declare const SCROLL_INTO_VIEW_SPEC: VerbSpec;
+export declare function getVerbSpec(verbName: string): VerbSpec | null;
+//# sourceMappingURL=actionSpecs.d.ts.map

package/dist/actionSpecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionSpecs.d.ts","sourceRoot":"","sources":["../src/actionSpecs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAM/D,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACjD,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAChF,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAErG;;+EAE+E;AAC/E,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAAqB,CAAC;AA0D7E,eAAO,MAAM,UAAU,EAAE,QAkBxB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,QAc3B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,QAUxB,CAAC;AAKF,eAAO,MAAM,eAAe,EAAE,QAgB7B,CAAC;AAIF,eAAO,MAAM,gBAAgB,EAAE,QAmB9B,CAAC;AAIF,eAAO,MAAM,UAAU,EAAE,QAOxB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,QAUvB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,QASvB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,QASxB,CAAC;AAoBF,gFAAgF;AAChF,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAQnF;AAsDD,eAAO,MAAM,oBAAoB,EAAE,QAiBlC,CAAC;AAIF,eAAO,MAAM,qBAAqB,EAAE,QAenC,CAAC;AAsBF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAE7D"}

package/dist/actionSpecs.js

@@ -0,0 +1,354 @@
+import { asText } from './helpers/text.js';
+import { log } from './log.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const DEFAULT_RECOVERABLE_NAMES = ['TimeoutError'];
+function kw(args) {
+    // Trailing options object convention: the last arg when it's a plain object.
+    const last = args[args.length - 1];
+    if (last !== null && typeof last === 'object' && !Array.isArray(last)) {
+        return last;
+    }
+    return {};
+}
+/** Press modifier keys; returns a releaser that ups them in reverse. */
+async function holdModifiers(page, modifiers) {
+    const mods = Array.isArray(modifiers) ? modifiers : [];
+    if (!mods.length)
+        return async () => { };
+    for (const m of mods)
+        await page.keyboard.down(m);
+    return async () => {
+        for (const m of [...mods].reverse())
+            await page.keyboard.up(m);
+    };
+}
+/**
+ * Selenium-parity bridge: rewrite `<option>.click()` into
+ * `<select>.selectOption({label})` on the ancestor. A native option inside a
+ * closed select is not clickable in modern browsers; without the bridge the
+ * verb sinks into the cascade, whose tiers can't see closed-dropdown text.
+ * Returns true when the bridge fired (caller skips the real click).
+ */
+async function tryOptionBridge(locator) {
+    let tag;
+    try {
+        // Real function, NOT a string — the grid CDP relay returns undefined
+        // for string page-functions.
+        tag = await locator.evaluate((el) => el && el.tagName);
+    }
+    catch {
+        return false;
+    }
+    if (typeof tag !== 'string' || tag.toUpperCase() !== 'OPTION')
+        return false;
+    const parent = locator.locator('xpath=ancestor::select[1]');
+    try {
+        if ((await parent.count()) === 0)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    let label;
+    try {
+        label = await locator.evaluate((el) => el.textContent || '');
+    }
+    catch {
+        return false;
+    }
+    const text = String(label ?? '').trim();
+    if (!text)
+        return false;
+    await parent.selectOption({ label: text });
+    return true;
+}
+// ── click / dblclick / hover ──────────────────────────────────────────────────
+export const CLICK_SPEC = {
+    runner: async (locator, ...args) => {
+        if (await tryOptionBridge(locator))
+            return;
+        await locator.click(kw(args));
+    },
+    coordRunner: async (page, x, y, ...args) => {
+        const o = kw(args);
+        const release = await holdModifiers(page, o['modifiers']);
+        try {
+            await page.mouse.click(x, y, {
+                button: o['button'] ?? 'left',
+                clickCount: o['clickCount'] ?? 1,
+                delay: o['delay'] ?? 0,
+            });
+        }
+        finally {
+            await release();
+        }
+    },
+};
+export const DBLCLICK_SPEC = {
+    runner: async (locator, ...args) => { await locator.dblclick(kw(args)); },
+    coordRunner: async (page, x, y, ...args) => {
+        const o = kw(args);
+        const release = await holdModifiers(page, o['modifiers']);
+        try {
+            await page.mouse.dblclick(x, y, {
+                button: o['button'] ?? 'left',
+                delay: o['delay'] ?? 0,
+            });
+        }
+        finally {
+            await release();
+        }
+    },
+};
+export const HOVER_SPEC = {
+    runner: async (locator, ...args) => { await locator.hover(kw(args)); },
+    coordRunner: async (page, x, y, ...args) => {
+        const release = await holdModifiers(page, kw(args)['modifiers']);
+        try {
+            await page.mouse.move(x, y);
+        }
+        finally {
+            await release();
+        }
+    },
+};
+// ── long_press / multi_click (V3 gestures) ────────────────────────────────────
+// hover → down → hold (duration + 0.1s buffer) → up (V2 _do_long_press parity).
+export const LONG_PRESS_SPEC = {
+    runner: async (locator, ...args) => {
+        const duration = Number(kw(args)['duration'] ?? 0) || 0;
+        const page = locator.page();
+        await locator.hover();
+        await page.mouse.down();
+        await sleep((duration + 0.1) * 1000);
+        await page.mouse.up();
+    },
+    coordRunner: async (page, x, y, ...args) => {
+        const duration = Number(kw(args)['duration'] ?? 0) || 0;
+        await page.mouse.move(x, y);
+        await page.mouse.down();
+        await sleep((duration + 0.1) * 1000);
+        await page.mouse.up();
+    },
+};
+// N discrete clicks on ONE resolved target — the cascade resolves once, the
+// runner clicks N times (V2 _do_multi_click parity). freq<=2 never reach here.
+export const MULTI_CLICK_SPEC = {
+    runner: async (locator, ...args) => {
+        const o = kw(args);
+        const frequency = Math.trunc(Number(o['frequency'] ?? 0));
+        const gap = Number(o['gap'] ?? 0.1);
+        for (let i = 0; i < frequency; i++) {
+            await locator.click();
+            if (i < frequency - 1)
+                await sleep(gap * 1000);
+        }
+    },
+    coordRunner: async (page, x, y, ...args) => {
+        const o = kw(args);
+        const frequency = Math.trunc(Number(o['frequency'] ?? 0));
+        const gap = Number(o['gap'] ?? 0.1);
+        for (let i = 0; i < frequency; i++) {
+            await page.mouse.click(x, y);
+            if (i < frequency - 1)
+                await sleep(gap * 1000);
+        }
+    },
+};
+// ── clear / fill / type / press (text-input verbs) ────────────────────────────
+export const CLEAR_SPEC = {
+    runner: async (locator, ...args) => { await locator.clear(kw(args)); },
+    coordRunner: async (page, x, y) => {
+        await page.mouse.click(x, y);
+        await page.keyboard.press('Control+a');
+        await page.keyboard.press('Delete');
+    },
+};
+export const FILL_SPEC = {
+    runner: async (locator, value, ...args) => {
+        await locator.fill(asText(value), kw(args));
+    },
+    coordRunner: async (page, x, y, value) => {
+        // Click + Ctrl+A + type — Playwright fill semantics (replace existing).
+        await page.mouse.click(x, y);
+        await page.keyboard.press('Control+a');
+        await page.keyboard.type(asText(value));
+    },
+};
+export const TYPE_SPEC = {
+    runner: async (locator, text, ...args) => {
+        await locator.pressSequentially(asText(text), kw(args));
+    },
+    coordRunner: async (page, x, y, text, ...args) => {
+        const delay = Number(kw(args)['delay'] ?? 0);
+        await page.mouse.click(x, y);
+        await page.keyboard.type(asText(text), { delay });
+    },
+};
+export const PRESS_SPEC = {
+    runner: async (locator, key, ...args) => {
+        await locator.press(String(key), kw(args));
+    },
+    coordRunner: async (page, x, y, key, ...args) => {
+        const delay = Number(kw(args)['delay'] ?? 0);
+        await page.mouse.click(x, y);
+        await page.keyboard.press(String(key), { delay });
+    },
+};
+// ── set_input_files ───────────────────────────────────────────────────────────
+// Real function, NOT a string — the grid CDP relay returns undefined for
+// string page-functions.
+const FIND_FIRST_FILE_INPUT_FN = () => {
+    const found = [];
+    const collect = (root) => {
+        let direct = [];
+        try {
+            direct = root.querySelectorAll('input[type=file]');
+        }
+        catch { /* skip */ }
+        for (const inp of direct)
+            found.push(inp);
+        let all = [];
+        try {
+            all = root.querySelectorAll('*');
+        }
+        catch { /* skip */ }
+        for (const host of all) {
+            if (host.shadowRoot)
+                collect(host.shadowRoot);
+        }
+    };
+    collect(document);
+    return found.length ? found[0] : null;
+};
+/** First <input type=file> via pure DOM (light + open shadow). Never raises. */
+export async function resolveFileInputDom(page) {
+    try {
+        const handle = await page.evaluateHandle(FIND_FIRST_FILE_INPUT_FN);
+        return handle.asElement();
+    }
+    catch {
+        log.helper('    [upload] DOM file-input probe failed');
+        return null;
+    }
+}
+// Real function, NOT a string — the grid CDP relay returns undefined for
+// string page-functions.
+const RESOLVE_FILE_INPUT_FN = ([x, y]) => {
+    const isFile = (n) => !!n && n.tagName === 'INPUT' && (n.type || '').toLowerCase() === 'file';
+    const el = document.elementFromPoint(x, y);
+    if (isFile(el))
+        return el;
+    if (el && el.closest) {
+        const lbl = el.closest('label');
+        if (lbl && isFile(lbl.control))
+            return lbl.control;
+    }
+    let node = el;
+    while (node) {
+        if (isFile(node))
+            return node;
+        if (node.shadowRoot) {
+            const inner = node.shadowRoot.querySelector('input[type=file]');
+            if (inner)
+                return inner;
+        }
+        if (node.querySelector) {
+            const inner = node.querySelector('input[type=file]');
+            if (inner)
+                return inner;
+        }
+        const root = node.getRootNode && node.getRootNode();
+        node = node.parentElement || (root instanceof ShadowRoot ? root.host : null);
+    }
+    const found = [];
+    const collect = (root) => {
+        let direct = [];
+        try {
+            direct = root.querySelectorAll('input[type=file]');
+        }
+        catch { /* skip */ }
+        for (const inp of direct)
+            found.push(inp);
+        let all = [];
+        try {
+            all = root.querySelectorAll('*');
+        }
+        catch { /* skip */ }
+        for (const host of all) {
+            if (host.shadowRoot)
+                collect(host.shadowRoot);
+        }
+    };
+    collect(document);
+    if (found.length === 1)
+        return found[0];
+    if (found.length > 1) {
+        let best = null;
+        let bestDist = Infinity;
+        for (const inp of found) {
+            const r = inp.getBoundingClientRect();
+            const cx = r.left + r.width / 2, cy = r.top + r.height / 2;
+            const d = (cx - x) * (cx - x) + (cy - y) * (cy - y);
+            if (d < bestDist) {
+                bestDist = d;
+                best = inp;
+            }
+        }
+        return best;
+    }
+    return null;
+};
+export const SET_INPUT_FILES_SPEC = {
+    runner: async (locator, files) => {
+        await locator.setInputFiles(files);
+    },
+    coordRunner: async (page, x, y, files) => {
+        const handle = await page.evaluateHandle(RESOLVE_FILE_INPUT_FN, [x, y]);
+        const element = handle.asElement();
+        if (element === null) {
+            throw new Error(`set_input_files: no <input type='file'> at/near healed coordinate (${x}, ${y})`);
+        }
+        await element.setInputFiles(files);
+    },
+    // DESKTOP_LOCATE primary (file inputs live in shadow roots / off-viewport);
+    // VISION_QUERY retained as the selector fallback.
+    tiers: ['DESKTOP_LOCATE', 'VISION_QUERY'],
+};
+// ── scroll_into_view ──────────────────────────────────────────────────────────
+export const SCROLL_INTO_VIEW_SPEC = {
+    runner: async (locator, ...args) => {
+        await locator.scrollIntoViewIfNeeded(kw(args));
+    },
+    coordRunner: async (page, x, y) => {
+        // Idempotent fine-adjustment after the full-page tier scrolled (spec §9.3).
+        await page.evaluate(([px, py]) => {
+            const el = document.elementFromPoint(px, py);
+            if (el)
+                el.scrollIntoView({ block: 'center' });
+        }, [x, y]);
+    },
+    tiers: ['DESKTOP_LOCATE_FULL_PAGE', 'VISION_QUERY'],
+};
+// ── Verb registry ─────────────────────────────────────────────────────────────
+const VERB_SPECS = {
+    click: CLICK_SPEC,
+    dblclick: DBLCLICK_SPEC,
+    long_press: LONG_PRESS_SPEC,
+    multi_click: MULTI_CLICK_SPEC,
+    hover: HOVER_SPEC,
+    clear: CLEAR_SPEC,
+    fill: FILL_SPEC,
+    type: TYPE_SPEC,
+    press: PRESS_SPEC,
+    set_input_files: SET_INPUT_FILES_SPEC,
+    scroll_into_view_if_needed: SCROLL_INTO_VIEW_SPEC,
+    // Playwright-JS method-name aliases (the heal patch passes the method name).
+    pressSequentially: TYPE_SPEC,
+    setInputFiles: SET_INPUT_FILES_SPEC,
+    scrollIntoViewIfNeeded: SCROLL_INTO_VIEW_SPEC,
+};
+export function getVerbSpec(verbName) {
+    return VERB_SPECS[verbName] ?? null;
+}
+//# sourceMappingURL=actionSpecs.js.map