@testmuai/playwright-bindings 0.1.26 → 0.1.27

package/dist/helpers/condition.js

@@ -0,0 +1,292 @@
+/**
+ * Condition classes for test evaluation — the V3 local-eval core.
+ *
+ * Port of PY testmu/_helpers/condition.py (itself ported from the Selenium
+ * binding). Consumed by exported test.js as LIVE OBJECTS — never a
+ * stringified repr the binding evals (the V3 PW-JS contract's deliberate
+ * divergence; eval under ESM is bundler- and CSP-hostile):
+ *
+ *   const [ok] = await new Condition({
+ *     conditions: [new ResolvedCondition('{{x}}', PossibleCondition('=='), '5')],
+ *     connectors: [],
+ *   }).evaluate();
+ *
+ * PossibleCondition is a CALLABLE const-object, not a TS enum: Python enums
+ * are callable by value, and the generator emits PossibleCondition('==') in
+ * both languages — a TS enum cannot keep that emission shape.
+ *
+ * Day-1 corner cases baked in (skill catalog Top-15):
+ *  #3 connector fold combines the accumulator with results[i+1];
+ *  #4 CONTAINS means right-in-left (left is the haystack);
+ *  unknown operators/connectors THROW — never a silent wrong verdict.
+ */
+import { isV3 } from '../configure.js';
+import { normalizeText } from './textNormalize.js';
+import { resolveVar } from '../vars.js';
+// ── Operators ─────────────────────────────────────────────────────────────────
+const POSSIBLE_CONDITION_VALUES = [
+    '==', '!=', '>', '<', '>=', '<=',
+    'contains', 'not_contains', 'starts_with', 'ends_with',
+];
+function possibleConditionFn(raw) {
+    const v = raw;
+    // No fallback: an unrecognized operator must throw rather than silently
+    // defaulting to EQUALS and producing a wrong verdict (PY parity).
+    if (!POSSIBLE_CONDITION_VALUES.includes(v)) {
+        throw new Error(`'${raw}' is not a valid PossibleCondition`);
+    }
+    return v;
+}
+export const PossibleCondition = Object.assign(possibleConditionFn, {
+    EQUALS: '==', NOT_EQUALS: '!=',
+    GREATER_THAN: '>', LESS_THAN: '<',
+    GREATER_THAN_OR_EQUALS: '>=', LESS_THAN_OR_EQUALS: '<=',
+    CONTAINS: 'contains', NOT_CONTAINS: 'not_contains',
+    STARTS_WITH: 'starts_with', ENDS_WITH: 'ends_with',
+});
+function concatenationOperatorFn(raw) {
+    const v = raw.toUpperCase();
+    if (v !== 'AND' && v !== 'OR') {
+        throw new Error(`'${raw}' is not a valid ConcatenationOperator`);
+    }
+    return v;
+}
+export const ConcatenationOperator = Object.assign(concatenationOperatorFn, { AND: 'AND', OR: 'OR' });
+// ── ResolvedCondition ─────────────────────────────────────────────────────────
+/** A single comparison triple: left_operand op right_operand. */
+export class ResolvedCondition {
+    leftOperand;
+    operator;
+    rightOperand;
+    constructor(leftOperand, operator, rightOperand) {
+        this.leftOperand = leftOperand;
+        this.operator = operator;
+        this.rightOperand = rightOperand;
+    }
+    toDict() {
+        return {
+            left_operand: this.leftOperand,
+            operator: this.operator,
+            right_operand: this.rightOperand,
+        };
+    }
+    /** Parse 'left op right' whitespace-delimited string. */
+    static fromString(condition) {
+        const parts = condition.split(/\s+/).filter(Boolean);
+        if (parts.length !== 3) {
+            throw new Error(`Cannot parse condition string: ${JSON.stringify(condition)}`);
+        }
+        const [left, op, right] = parts;
+        return new ResolvedCondition(left, PossibleCondition(op), right);
+    }
+    static fromJson(json) {
+        return new ResolvedCondition(json.left_operand ?? '', PossibleCondition(json.operator ?? ''), json.right_operand ?? '');
+    }
+    toString() {
+        return `${this.leftOperand} ${this.operator} ${this.rightOperand}`;
+    }
+    equals(other) {
+        return (other instanceof ResolvedCondition &&
+            this.leftOperand === other.leftOperand &&
+            this.operator === other.operator &&
+            this.rightOperand === other.rightOperand);
+    }
+}
+/** Default resolver: the binding's own variable store (async — ATMS/env). */
+const defaultResolver = (template) => resolveVar(template);
+/**
+ * Composite condition: ResolvedConditions joined by ConcatenationOperators.
+ * `await cond.evaluate()` returns `[boolean, usedVariables]`.
+ */
+export class Condition {
+    conditions;
+    connectors;
+    isV3;
+    constructor(opts) {
+        this.conditions = opts.conditions;
+        this.connectors = opts.connectors;
+        // V3 mode: text ops are case-insensitive + unicode-folded; AND binds
+        // tighter than OR (A OR B AND C == A OR (B AND C)). Resolved from the
+        // runtime config when not passed — codegen emits bare Condition({...})
+        // with no isV3 arg, so this is what makes those pick up V3 semantics.
+        this.isV3 = opts.isV3 ?? isV3();
+    }
+    // ── Internal helpers ────────────────────────────────────────────────────────
+    async resolvePlaceholder(s, variables, getVariableValue) {
+        if (getVariableValue) {
+            const result = await getVariableValue(s, variables);
+            return [result, { [s]: result }];
+        }
+        const t = s.trim();
+        if (t.startsWith('{{') && t.endsWith('}}')) {
+            const key = t.slice(2, -2).trim();
+            return [this.accessNestedValue(variables, key), { [key]: this.accessNestedValue(variables, key) }];
+        }
+        if (t.startsWith('${') && t.endsWith('}')) {
+            const key = t.slice(2, -1).trim();
+            return [this.accessNestedValue(variables, key), { [key]: this.accessNestedValue(variables, key) }];
+        }
+        return [s, {}]; // not a placeholder
+    }
+    /** Dotted + bracket-indexed traversal ('api_x.response_body.items[0].id'). */
+    accessNestedValue(dump, name) {
+        let value = dump;
+        for (let key of name.split('.')) {
+            while (key.includes('[') && key.includes(']')) {
+                const base = key.slice(0, key.indexOf('['));
+                const index = parseInt(key.slice(key.indexOf('[') + 1, key.indexOf(']')), 10);
+                if (base)
+                    value = value[base];
+                value = value[index];
+                key = key.slice(key.indexOf(']') + 1);
+            }
+            if (key) {
+                if (value === null || typeof value !== 'object') {
+                    throw new Error(`Variable '${name}' not found in variables`);
+                }
+                if (!(key in value)) {
+                    throw new Error(`Variable '${name}' not found in variables`);
+                }
+                value = value[key];
+            }
+        }
+        return value;
+    }
+    isNumeric(val) {
+        if (typeof val === 'number')
+            return Number.isFinite(val);
+        if (typeof val === 'string') {
+            const t = val.trim();
+            if (t === '')
+                return false;
+            return Number.isFinite(Number(t));
+        }
+        return false;
+    }
+    toNumeric(val) {
+        if (typeof val === 'number')
+            return val;
+        if (typeof val === 'string') {
+            const n = Number(val.trim());
+            return Number.isFinite(n) ? n : null;
+        }
+        return null;
+    }
+    cleanString(s) {
+        if ((s.startsWith('"') && s.endsWith('"')) ||
+            (s.startsWith("'") && s.endsWith("'"))) {
+            return s.slice(1, -1);
+        }
+        return s;
+    }
+    /** Coerce mixed string/number operands before comparing (PY parity). */
+    typecast(left, right) {
+        const leftIsStr = typeof left === 'string';
+        const rightIsStr = typeof right === 'string';
+        const leftIsNum = this.isNumeric(left);
+        const rightIsNum = this.isNumeric(right);
+        if (leftIsNum && rightIsNum) {
+            return [this.toNumeric(left), this.toNumeric(right)];
+        }
+        let l = leftIsStr ? this.cleanString(left) : left;
+        let r = rightIsStr ? this.cleanString(right) : right;
+        if (leftIsStr && rightIsNum && this.isNumeric(l)) {
+            l = this.toNumeric(l);
+        }
+        else if (rightIsStr && leftIsNum && this.isNumeric(r)) {
+            r = this.toNumeric(r);
+        }
+        return [l, r];
+    }
+    /** Normalize a text operand for substring/prefix/suffix comparison.
+     * V3: accent-fold + case-fold; V4: plain String(). */
+    cmp(x) {
+        return this.isV3 ? normalizeText(x, { caseInsensitive: true }) : String(x);
+    }
+    evalCondition(operator, leftOperand, rightOperand) {
+        let [left, right] = this.typecast(leftOperand, rightOperand);
+        // bool <-> "true"/"false" normalization.
+        if (typeof left === 'boolean' && typeof right === 'string') {
+            const lowered = right.trim().toLowerCase();
+            if (lowered === 'true' || lowered === 'false')
+                right = lowered === 'true';
+        }
+        else if (typeof right === 'boolean' && typeof left === 'string') {
+            const lowered = left.trim().toLowerCase();
+            if (lowered === 'true' || lowered === 'false')
+                left = lowered === 'true';
+        }
+        switch (operator) {
+            case '==': return left === right;
+            case '!=': return left !== right;
+            case '>': return left > right;
+            case '<': return left < right;
+            case '>=': return left >= right;
+            case '<=': return left <= right;
+            // CONTAINS: left is the HAYSTACK (right in left) — corner-case #4.
+            case 'contains': return this.cmp(left).includes(this.cmp(right));
+            case 'not_contains': return !this.cmp(left).includes(this.cmp(right));
+            case 'starts_with': return this.cmp(left).startsWith(this.cmp(right));
+            case 'ends_with': return this.cmp(left).endsWith(this.cmp(right));
+            default:
+                throw new Error(`Unsupported condition: ${String(operator)}`);
+        }
+    }
+    // ── Public API ──────────────────────────────────────────────────────────────
+    /**
+     * Evaluate all conditions. Returns `[result, usedVariables]`.
+     *
+     * With no arguments (the emitted-code shape) variables resolve through the
+     * binding's own store. Pass an explicit resolver/variables for local eval.
+     */
+    async evaluate(variables = {}, getVariableValue = defaultResolver) {
+        const used = {};
+        const results = [];
+        for (const condition of this.conditions) {
+            const [left, leftUsed] = await this.resolvePlaceholder(condition.leftOperand, variables, getVariableValue);
+            const [right, rightUsed] = await this.resolvePlaceholder(condition.rightOperand, variables, getVariableValue);
+            results.push(this.evalCondition(condition.operator, left, right));
+            Object.assign(used, leftUsed, rightUsed);
+        }
+        if (this.isV3) {
+            // V3 precedence fold: AND binds tighter than OR. Accumulate AND-groups
+            // left-to-right; each OR flushes the running group.
+            if (results.length === 0)
+                return [true, used];
+            let current = results[0];
+            const orGroups = [];
+            this.connectors.forEach((connector, idx) => {
+                // Corner-case #3: the operand is results[idx + 1], never results[idx].
+                const operand = idx + 1 < results.length ? results[idx + 1] : false;
+                if (connector === 'AND')
+                    current = current && operand;
+                else if (connector === 'OR') {
+                    orGroups.push(current);
+                    current = operand;
+                }
+                else
+                    throw new Error(`Unsupported connector: ${String(connector)}`);
+            });
+            orGroups.push(current);
+            return [orGroups.some(Boolean), used];
+        }
+        let finalResult = results.length ? results[0] : true;
+        this.connectors.forEach((connector, idx) => {
+            const operand = results[idx + 1];
+            if (connector === 'AND')
+                finalResult = finalResult && operand;
+            else if (connector === 'OR')
+                finalResult = finalResult || operand;
+            else
+                throw new Error(`Unsupported connector: ${String(connector)}`);
+        });
+        return [finalResult, used];
+    }
+    toDict() {
+        return {
+            connectors: [...this.connectors],
+            conditions: this.conditions.map((c) => c.toDict()),
+        };
+    }
+}
+//# sourceMappingURL=condition.js.map

package/dist/helpers/condition.js.map

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

package/dist/helpers/cookies.d.ts

@@ -0,0 +1,12 @@
+/** Cookie read with V2 driver_query_script parity (playwright). */
+import type { BrowserContext } from 'playwright';
+/**
+ * Read cookies, then narrow by an attribute chain and an optional field.
+ *
+ * `attributes` entries are either `{index: n}` (array index) or
+ * `{<any>: [key]}` / `{<any>: [key, value]}` — a single-element array reads the
+ * key, a pair searches for the object whose key equals value.
+ * `field` is one of "len" | "keys" | "values", else the narrowed value is returned.
+ */
+export declare function getCookies(context: BrowserContext, attributes?: Array<Record<string, unknown>> | null, field?: string): Promise<unknown>;
+//# sourceMappingURL=cookies.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/helpers/cookies.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAyBjD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,EAClD,KAAK,SAAK,GACT,OAAO,CAAC,OAAO,CAAC,CAiClB"}

package/dist/helpers/cookies.js

@@ -0,0 +1,66 @@
+import { log } from '../log.js';
+/** Depth-first search for the first object whose `key` equals `value`. */
+function findObjectWithKv(data, key, value) {
+    if (Array.isArray(data)) {
+        for (const item of data) {
+            const found = findObjectWithKv(item, key, value);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (data !== null && typeof data === 'object') {
+        const obj = data;
+        if (obj[key] === value)
+            return obj;
+        for (const v of Object.values(obj)) {
+            const found = findObjectWithKv(v, key, value);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * Read cookies, then narrow by an attribute chain and an optional field.
+ *
+ * `attributes` entries are either `{index: n}` (array index) or
+ * `{<any>: [key]}` / `{<any>: [key, value]}` — a single-element array reads the
+ * key, a pair searches for the object whose key equals value.
+ * `field` is one of "len" | "keys" | "values", else the narrowed value is returned.
+ */
+export async function getCookies(context, attributes, field = '') {
+    const attrs = attributes ?? [];
+    log.helper(`    [getCookies] attributes=${JSON.stringify(attrs)} field=${JSON.stringify(field)}`);
+    let queried = await context.cookies();
+    for (const attr of attrs) {
+        for (const [key, value] of Object.entries(attr)) {
+            if (key === 'index') {
+                queried = queried[Number(value)] ?? null;
+                continue;
+            }
+            const query = value;
+            if (query.length === 1) {
+                const obj = (queried ?? {});
+                queried = obj[String(query[0])] ?? '';
+            }
+            else {
+                queried = findObjectWithKv(queried, String(query[0]), query[1]);
+                if (queried === null) {
+                    throw new Error(`Key ${String(query[0])} with value ${String(query[1])} not found in queried content.`);
+                }
+            }
+        }
+    }
+    if (field === 'len') {
+        if (Array.isArray(queried) || typeof queried === 'string')
+            return queried.length;
+        return Object.keys((queried ?? {})).length;
+    }
+    if (field === 'keys')
+        return Object.keys((queried ?? {}));
+    if (field === 'values')
+        return Object.values((queried ?? {}));
+    return queried;
+}
+//# sourceMappingURL=cookies.js.map

package/dist/helpers/cookies.js.map

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

package/dist/helpers/coordinateResolver.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Coordinate → element → verified-XPath derivation (design spec §3.1, §4).
+ *
+ * playwright-ts twin of the PY/Selenium coordinate resolvers. RESOLVER_JS is
+ * the CANONICAL tree-shared script — it must stay byte-identical to the
+ * selenium-python / playwright-python copies (spec §4.3: edit ALL trees
+ * together).
+ */
+import type { Page } from 'playwright';
+export declare const RESOLVER_JS = "try {\n  var el = document.elementFromPoint(x, y);\n  if (!el) { return null; }\n  while (el.shadowRoot) {\n    var deeper = el.shadowRoot.elementFromPoint(x, y);\n    if (!deeper || deeper === el) { break; }\n    el = deeper;\n  }\n  if (el.getRootNode && el.getRootNode() !== document) { return null; }\n  var hitTag = el.tagName ? el.tagName.toLowerCase() : '';\n  if (hitTag === 'iframe' || hitTag === 'frame' || hitTag === 'canvas' || hitTag === 'video') { return null; }\n\n  var INTERACTABLE = 'a, button, input, select, textarea, summary, label, [onclick], [contenteditable], [tabindex]:not([tabindex=\"-1\"]), [role=\"button\"], [role=\"link\"], [role=\"checkbox\"], [role=\"radio\"], [role=\"menuitem\"], [role=\"tab\"], [role=\"option\"], [role=\"switch\"], [role=\"combobox\"], [role=\"textbox\"]';\n  if (!(el.matches && el.matches(INTERACTABLE))) {\n    var cur = el;\n    var hops = 0;\n    while (cur && cur !== document.documentElement && hops < 6) {\n      cur = cur.parentElement;\n      hops += 1;\n      if (cur && cur.matches && cur.matches(INTERACTABLE)) { el = cur; break; }\n    }\n  }\n\n  function xpathLiteral(v) {\n    if (v.indexOf(\"'\") === -1) { return \"'\" + v + \"'\"; }\n    if (v.indexOf('\"') === -1) { return '\"' + v + '\"'; }\n    return \"concat('\" + v.split(\"'\").join(\"', \\\"'\\\", '\") + \"')\";\n  }\n\n  function verifies(xp) {\n    try {\n      var r = document.evaluate(xp, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);\n      return r.snapshotLength === 1 && r.snapshotItem(0) === el;\n    } catch (e) { return false; }\n  }\n\n  var tag = el.tagName.toLowerCase();\n  var candidates = [];\n  if (el.id) { candidates.push('//*[@id=' + xpathLiteral(el.id) + ']'); }\n  var ATTRS = ['data-testid', 'data-test', 'data-qa', 'name', 'aria-label', 'placeholder', 'title'];\n  for (var i = 0; i < ATTRS.length; i++) {\n    var av = el.getAttribute(ATTRS[i]);\n    if (av) { candidates.push('//' + tag + '[@' + ATTRS[i] + '=' + xpathLiteral(av) + ']'); break; }\n  }\n  var text = (el.textContent || '').replace(/\\s+/g, ' ').trim();\n  if (text && text.length <= 64) {\n    candidates.push('//' + tag + '[normalize-space(.)=' + xpathLiteral(text) + ']');\n  }\n  var parts = [];\n  var node = el;\n  while (node && node.nodeType === 1) {\n    var name = node.tagName.toLowerCase();\n    var idx = 1;\n    var sib = node.previousElementSibling;\n    while (sib) {\n      if (sib.tagName === node.tagName) { idx += 1; }\n      sib = sib.previousElementSibling;\n    }\n    parts.unshift(name + '[' + idx + ']');\n    node = node.parentElement;\n  }\n  candidates.push('/' + parts.join('/'));\n\n  for (var c = 0; c < candidates.length; c++) {\n    if (verifies(candidates[c])) {\n      return { xpath: candidates[c], tag: tag, id: el.id || '', text: text.slice(0, 80) };\n    }\n  }\n  return null;\n} catch (e) {\n  return null;\n}\n";
+/** A self-verified, document-rooted XPath for the element under a point. */
+export interface ResolvedTarget {
+    xpath: string;
+    meta: {
+        tag: string;
+        id: string;
+        text: string;
+    };
+}
+/**
+ * Resolve viewport-CSS (x, y) to a verified XPath, or null.
+ *
+ * null ALWAYS means "use the coordinate fallback" (shadow-DOM hit, iframe
+ * hit, no node, verification failure, or any JS error). Never throws — a
+ * derivation failure must never break a heal that would have succeeded via
+ * the coord runner (spec §3.1).
+ */
+export declare function resolveCoordinate(page: Page, x: number, y: number): Promise<ResolvedTarget | null>;
+//# sourceMappingURL=coordinateResolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coordinateResolver.d.ts","sourceRoot":"","sources":["../../src/helpers/coordinateResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIvC,eAAO,MAAM,WAAW,s1FAyEvB,CAAC;AAWF,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAyBhC"}

package/dist/helpers/coordinateResolver.js

@@ -0,0 +1,118 @@
+import { log } from '../log.js';
+// === CANONICAL_RESOLVER_JS_START === (edit ALL trees together; spec §4.3)
+export const 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') { return null; }
+
+  var INTERACTABLE = 'a, button, input, select, textarea, summary, label, [onclick], [contenteditable], [tabindex]:not([tabindex="-1"]), [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="menuitem"], [role="tab"], [role="option"], [role="switch"], [role="combobox"], [role="textbox"]';
+  if (!(el.matches && el.matches(INTERACTABLE))) {
+    var cur = el;
+    var hops = 0;
+    while (cur && cur !== document.documentElement && hops < 6) {
+      cur = cur.parentElement;
+      hops += 1;
+      if (cur && cur.matches && cur.matches(INTERACTABLE)) { el = cur; break; }
+    }
+  }
+
+  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_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_FN = new Function('args', 'const [x, y] = args;\n' + RESOLVER_JS);
+/**
+ * Resolve viewport-CSS (x, y) to a verified XPath, or null.
+ *
+ * null ALWAYS means "use the coordinate fallback" (shadow-DOM hit, iframe
+ * hit, no node, verification failure, or any JS error). Never throws — a
+ * derivation failure must never break a heal that would have succeeded via
+ * the coord runner (spec §3.1).
+ */
+export async function resolveCoordinate(page, x, y) {
+    let raw;
+    try {
+        raw = await page.evaluate(WRAPPED_FN, [Math.trunc(x), Math.trunc(y)]);
+    }
+    catch (exc) {
+        log.helper(`    [resolver] derived_xpath=None reason=js-error: ${String(exc)}`);
+        return null;
+    }
+    if (raw === null || typeof raw !== 'object') {
+        log.helper('    [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('    [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(`    [resolver] derived_xpath=${xpath} meta=${JSON.stringify(meta)}`);
+    return { xpath, meta };
+}
+//# sourceMappingURL=coordinateResolver.js.map

package/dist/helpers/coordinateResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinateResolver.js","sourceRoot":"","sources":["../../src/helpers/coordinateResolver.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyE1B,CAAC;AACF,oCAAoC;AAEpC,4EAA4E;AAC5E,uEAAuE;AACvE,0EAA0E;AAC1E,8DAA8D;AAC9D,MAAM,UAAU,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,wBAAwB,GAAG,WAAW,CAElE,CAAC;AAQb;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAU,EACV,CAAS,EACT,CAAS;IAET,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAmB,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAU,CAAC,CAAC;IAC1F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,MAAM,CAAC,sDAAsD,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,GAAG,CAAC,MAAM,CAAC,0DAA0D,CAAC,CAAC;QACvE,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,wDAAwD,CAAC,CAAC;QACrE,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,gCAAgC,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjF,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}

package/dist/helpers/coordinateResolverRead.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Read-tuned coordinate → element → verified-XPath (textual_query read path).
+ *
+ * playwright-ts read twin of PY _coordinate_resolver_read.py / selenium's
+ * READ_RESOLVER_JS. READ_RESOLVER_JS is CANONICAL and byte-shared across all
+ * three trees (spec §4.3: edit ALL trees together).
+ *
+ * Key difference from coordinateResolver.ts / RESOLVER_JS:
+ *   The interactable ancestor up-walk (INTERACTABLE selector + 6-hop
+ *   parentElement loop) is OMITTED, and img is a bail tag. `el` stays the
+ *   exact elementFromPoint hit, so non-inherited CSS (background-color) is
+ *   read from the correct box, not a climbed a/button/[role] ancestor.
+ */
+import type { Page } from 'playwright';
+export declare const READ_RESOLVER_JS = "try {\n  var el = document.elementFromPoint(x, y);\n  if (!el) { return null; }\n  while (el.shadowRoot) {\n    var deeper = el.shadowRoot.elementFromPoint(x, y);\n    if (!deeper || deeper === el) { break; }\n    el = deeper;\n  }\n  if (el.getRootNode && el.getRootNode() !== document) { return null; }\n  var hitTag = el.tagName ? el.tagName.toLowerCase() : '';\n  if (hitTag === 'iframe' || hitTag === 'frame' || hitTag === 'canvas' || hitTag === 'video' || hitTag === 'img') { return null; }\n\n  // *** NO interactable up-walk here (the ONLY structural difference from\n  // RESOLVER_JS): the read must stay on the exact direct hit so non-inherited\n  // CSS (background-color) is read off the correct box. ***\n\n  function xpathLiteral(v) {\n    if (v.indexOf(\"'\") === -1) { return \"'\" + v + \"'\"; }\n    if (v.indexOf('\"') === -1) { return '\"' + v + '\"'; }\n    return \"concat('\" + v.split(\"'\").join(\"', \\\"'\\\", '\") + \"')\";\n  }\n  function verifies(xp) {\n    try {\n      var r = document.evaluate(xp, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);\n      return r.snapshotLength === 1 && r.snapshotItem(0) === el;\n    } catch (e) { return false; }\n  }\n  var tag = el.tagName.toLowerCase();\n  var candidates = [];\n  if (el.id) { candidates.push('//*[@id=' + xpathLiteral(el.id) + ']'); }\n  var ATTRS = ['data-testid', 'data-test', 'data-qa', 'name', 'aria-label', 'placeholder', 'title'];\n  for (var i = 0; i < ATTRS.length; i++) {\n    var av = el.getAttribute(ATTRS[i]);\n    if (av) { candidates.push('//' + tag + '[@' + ATTRS[i] + '=' + xpathLiteral(av) + ']'); break; }\n  }\n  var text = (el.textContent || '').replace(/\\s+/g, ' ').trim();\n  if (text && text.length <= 64) {\n    candidates.push('//' + tag + '[normalize-space(.)=' + xpathLiteral(text) + ']');\n  }\n  var parts = [];\n  var node = el;\n  while (node && node.nodeType === 1) {\n    var name = node.tagName.toLowerCase();\n    var idx = 1;\n    var sib = node.previousElementSibling;\n    while (sib) { if (sib.tagName === node.tagName) { idx += 1; } sib = sib.previousElementSibling; }\n    parts.unshift(name + '[' + idx + ']');\n    node = node.parentElement;\n  }\n  candidates.push('/' + parts.join('/'));\n  for (var c = 0; c < candidates.length; c++) {\n    if (verifies(candidates[c])) {\n      return { xpath: candidates[c], tag: tag, id: el.id || '', text: text.slice(0, 80) };\n    }\n  }\n  return null;\n} catch (e) {\n  return null;\n}\n";
+/** A self-verified, document-rooted XPath for the element under a point (read path). */
+export interface ResolvedRead {
+    xpath: string;
+    meta: {
+        tag: string;
+        id: string;
+        text: string;
+    };
+}
+/**
+ * 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 declare function resolveCoordinateRead(page: Page, x: number, y: number): Promise<ResolvedRead | null>;
+//# sourceMappingURL=coordinateResolverRead.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coordinateResolverRead.d.ts","sourceRoot":"","sources":["../../src/helpers/coordinateResolverRead.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAIvC,eAAO,MAAM,gBAAgB,m7EA4D5B,CAAC;AAWF,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAyB9B"}