@applitools/eyes-results 0.2.0

package/dist/sessions/dom-search.js

@@ -0,0 +1,1150 @@
+// ---------------------------------------------------------------------------
+// dom-search: a small predicate language for querying DOM capture files
+// ---------------------------------------------------------------------------
+//
+// Mostly self-contained — duplicates a handful of tiny dom.ts helpers (node ids, text
+// aggregation, rect extraction) rather than import them, since they're small and stable
+// enough that keeping this file independently readable outweighs the duplication. Visibility
+// is the one exception: `isVisible` is imported for real from dom.ts, where it belongs as a
+// general DOM-node concept — this file has no reason to own its own copy of that logic, and
+// nothing here flows back into dom.ts, so there's no circularity to worry about.
+import { isVisible } from './dom.js';
+const WORD_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:-[A-Za-z0-9_]+)*/;
+const ORDINAL_SUFFIX_RE = /^(\d+)(st|nd|rd|th)\b/i;
+// Escapes recognized inside a single-quoted value. `"` is deliberately absent — there is no
+// double-quoted form, so a literal double quote never needs escaping and `\"` passes through
+// as its own two literal characters rather than being treated as an escape.
+const STRING_ESCAPES = {
+    "'": "'",
+    '\\': '\\',
+    n: '\n',
+    t: '\t',
+    r: '\r',
+};
+function scanString(src, start) {
+    let i = start + 1;
+    let value = '';
+    while (i < src.length && src[i] !== "'") {
+        const escaped = src[i] === '\\' ? STRING_ESCAPES[src[i + 1]] : undefined;
+        if (escaped !== undefined) {
+            value += escaped;
+            i += 2;
+        }
+        else {
+            value += src[i];
+            i++;
+        }
+    }
+    if (i >= src.length) {
+        throw new Error(`Unterminated string literal starting at position ${start} — a single-quoted value must be closed with '.`);
+    }
+    return { value, end: i + 1 };
+}
+function scanRegex(src, start) {
+    let i = start + 1;
+    let pattern = '';
+    while (i < src.length && src[i] !== '/') {
+        if (src[i] === '\\' && i + 1 < src.length) {
+            pattern += src[i] + src[i + 1];
+            i += 2;
+            continue;
+        }
+        pattern += src[i];
+        i++;
+    }
+    if (i >= src.length) {
+        throw new Error(`Unterminated regex literal starting at position ${start} — a /pattern/ must be closed with /.`);
+    }
+    i++; // consume closing '/'
+    let flags = '';
+    while (i < src.length && /[a-zA-Z]/.test(src[i])) {
+        flags += src[i];
+        i++;
+    }
+    return { pattern, flags, end: i };
+}
+function tokenize(src) {
+    const tokens = [];
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        const start = i;
+        if (c === '(' || c === ')' || c === ',' || c === '.') {
+            tokens.push({ type: 'punct', value: c, pos: start });
+            i++;
+            continue;
+        }
+        if (c === '&' && src[i + 1] === '&') {
+            tokens.push({ type: 'punct', value: '&&', pos: start });
+            i += 2;
+            continue;
+        }
+        if (c === '|' && src[i + 1] === '|') {
+            tokens.push({ type: 'punct', value: '||', pos: start });
+            i += 2;
+            continue;
+        }
+        if (c === '!' && src[i + 1] === '=') {
+            tokens.push({ type: 'punct', value: '!=', pos: start });
+            i += 2;
+            continue;
+        }
+        if (c === '<' && src[i + 1] === '=') {
+            tokens.push({ type: 'punct', value: '<=', pos: start });
+            i += 2;
+            continue;
+        }
+        if (c === '>' && src[i + 1] === '=') {
+            tokens.push({ type: 'punct', value: '>=', pos: start });
+            i += 2;
+            continue;
+        }
+        if (c === '=' && src[i + 1] === '~') {
+            tokens.push({ type: 'punct', value: '=~', pos: start });
+            i += 2;
+            continue;
+        }
+        if (c === '!') {
+            tokens.push({ type: 'punct', value: '!', pos: start });
+            i++;
+            continue;
+        }
+        if (c === '<') {
+            tokens.push({ type: 'punct', value: '<', pos: start });
+            i++;
+            continue;
+        }
+        if (c === '>') {
+            tokens.push({ type: 'punct', value: '>', pos: start });
+            i++;
+            continue;
+        }
+        if (c === '=') {
+            tokens.push({ type: 'punct', value: '=', pos: start });
+            i++;
+            continue;
+        }
+        if (c === "'") {
+            const { value, end } = scanString(src, i);
+            tokens.push({ type: 'string', value, pos: start });
+            i = end;
+            continue;
+        }
+        if (c === '/') {
+            const { pattern, flags, end } = scanRegex(src, i);
+            tokens.push({ type: 'regex', value: pattern, flags, pos: start });
+            i = end;
+            continue;
+        }
+        const isDigitStart = /[0-9]/.test(c);
+        const isNegativeStart = c === '-' && /[0-9]/.test(src[i + 1] ?? '');
+        if (isDigitStart || isNegativeStart) {
+            let j = isNegativeStart ? i + 1 : i;
+            while (/[0-9]/.test(src[j] ?? ''))
+                j++;
+            const digitsEnd = j;
+            if (!isNegativeStart) {
+                const ordinalMatch = ORDINAL_SUFFIX_RE.exec(src.slice(i));
+                if (ordinalMatch) {
+                    const word = ordinalMatch[0];
+                    tokens.push({ type: 'word', value: word, pos: start });
+                    i += word.length;
+                    continue;
+                }
+            }
+            let k = digitsEnd;
+            if (src[k] === '.' && /[0-9]/.test(src[k + 1] ?? '')) {
+                k++;
+                while (/[0-9]/.test(src[k] ?? ''))
+                    k++;
+            }
+            tokens.push({ type: 'number', value: src.slice(i, k), pos: start });
+            i = k;
+            continue;
+        }
+        if (/[A-Za-z_]/.test(c)) {
+            const match = WORD_RE.exec(src.slice(i));
+            const word = match[0];
+            tokens.push({ type: 'word', value: word, pos: start });
+            i += word.length;
+            continue;
+        }
+        throw new Error(`Unexpected character '${c}' at position ${start} in predicate.`);
+    }
+    tokens.push({ type: 'eof', value: '', pos: src.length });
+    return tokens;
+}
+// ---------------------------------------------------------------------------
+// Keyword tables
+// ---------------------------------------------------------------------------
+const BOUNDS_OPS = new Set(['contains', 'intersects', 'contained-by']);
+const BOUNDS_OP_CANON = {
+    contains: 'contains',
+    intersects: 'intersects',
+    'contained-by': 'containedBy',
+};
+const RELATION_KIND = {
+    'descendant-of': 'descendant',
+    'descendent-of': 'descendant',
+    'ancestor-of': 'ancestor',
+    'child-of': 'child',
+    'parent-of': 'parent',
+    'sibling-of': 'sibling',
+};
+const NULLARY_WORDS = new Set([
+    'text',
+    'image',
+    'gif',
+    'logo',
+    'link',
+    'button',
+    'heading',
+    'hidden',
+    'visible',
+    'empty',
+    'true',
+    'false',
+]);
+const SIZE_OP_KIND = {
+    'larger-than': 'larger',
+    'smaller-than': 'smaller',
+    'wider-than': 'wider',
+    'narrower-than': 'narrower',
+    'taller-than': 'taller',
+    'shorter-than': 'shorter',
+};
+const DIR_OP_KIND = {
+    above: 'above',
+    below: 'below',
+    'left-of': 'leftOf',
+    'right-of': 'rightOf',
+};
+const _VALID_SIZE_OPS_LIST = 'larger-than, smaller-than, wider-than, narrower-than, taller-than, shorter-than';
+const VALID_DIR_OPS_LIST = 'above, below, left-of, right-of';
+const COMPARE_OP_MAP = {
+    '=': 'eq',
+    equals: 'eq',
+    '!=': 'neq',
+    'not-equals': 'neq',
+    '<': 'lt',
+    'less-than': 'lt',
+    '<=': 'lte',
+    'less-than-or-equal': 'lte',
+    'less-than-or-equal-to': 'lte',
+    '>': 'gt',
+    'greater-than': 'gt',
+    '>=': 'gte',
+    'greater-than-or-equal': 'gte',
+    'greater-than-or-equal-to': 'gte',
+    'starts-with': 'startsWith',
+    'ends-with': 'endsWith',
+    contains: 'contains',
+    '=~': 'regex',
+    matches: 'regex',
+    regex: 'regex',
+    in: 'in',
+};
+const VALID_COMPARE_OPS_LIST = '=, equals, !=, not-equals, <, less-than, <=, less-than-or-equal, less-than-or-equal-to, ' +
+    '>, greater-than, >=, greater-than-or-equal, greater-than-or-equal-to, starts-with, ends-with, ' +
+    'contains, =~, matches, regex, in';
+const VALID_BOUNDS_OPS_LIST = 'contains, intersects, contained-by';
+const VALID_NULLARY_LIST = 'text, image, gif, logo, link, button, heading, hidden, visible, empty, true, false';
+const VALID_RELATION_LIST = "descendant-of, descendent-of, ancestor-of, child-of, parent-of, sibling-of (optionally preceded by an ordinal like '2nd' or 'first' for child-of)";
+const ORDINAL_WORDS = {
+    first: 1,
+    second: 2,
+    third: 3,
+    fourth: 4,
+    fifth: 5,
+    sixth: 6,
+    seventh: 7,
+    eighth: 8,
+    ninth: 9,
+    tenth: 10,
+    eleventh: 11,
+    twelfth: 12,
+    thirteenth: 13,
+    fourteenth: 14,
+    fifteenth: 15,
+    sixteenth: 16,
+    seventeenth: 17,
+    eighteenth: 18,
+    nineteenth: 19,
+    twentieth: 20,
+};
+function isOrdinalToken(text) {
+    const lower = text.toLowerCase();
+    if (lower in ORDINAL_WORDS)
+        return true;
+    return /^\d+(st|nd|rd|th)$/i.test(lower);
+}
+function parseOrdinalValue(text) {
+    const lower = text.toLowerCase();
+    if (lower in ORDINAL_WORDS)
+        return ORDINAL_WORDS[lower];
+    const m = /^(\d+)(st|nd|rd|th)$/i.exec(lower);
+    if (m) {
+        const n = Number(m[1]);
+        if (n >= 1 && n <= 20)
+            return n;
+    }
+    throw new Error(`Ordinal '${text}' is out of range. Only 1st through 20th (or 'first' through 'twentieth') are supported.`);
+}
+function tokenOpKey(tok) {
+    if (tok.type === 'punct')
+        return COMPARE_OP_MAP[tok.value] ?? null;
+    if (tok.type === 'word')
+        return COMPARE_OP_MAP[tok.value.toLowerCase()] ?? null;
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+class Parser {
+    tokens;
+    pos = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    peek(offset = 0) {
+        return this.tokens[Math.min(this.pos + offset, this.tokens.length - 1)];
+    }
+    next() {
+        const tok = this.tokens[this.pos];
+        if (this.pos < this.tokens.length - 1)
+            this.pos++;
+        return tok;
+    }
+    isWord(tok, text) {
+        return tok.type === 'word' && tok.value.toLowerCase() === text;
+    }
+    isPunct(tok, text) {
+        return tok.type === 'punct' && tok.value === text;
+    }
+    expectPunct(sym) {
+        const tok = this.peek();
+        if (!this.isPunct(tok, sym)) {
+            const shown = tok.type === 'eof' ? 'end of predicate' : `'${tok.value}'`;
+            throw new Error(`Unexpected token ${shown} at position ${tok.pos} — expected '${sym}'.`);
+        }
+        this.next();
+    }
+    parseTopLevel() {
+        const ast = this.parseExpr();
+        const rest = this.peek();
+        if (rest.type !== 'eof') {
+            throw new Error(`Unexpected trailing input starting at '${rest.value}' (position ${rest.pos}) — the predicate finished parsing before the end of the string.`);
+        }
+        return ast;
+    }
+    parseExpr() {
+        return this.parseOr();
+    }
+    parseOr() {
+        let left = this.parseAnd();
+        while (this.isWord(this.peek(), 'or') || this.isPunct(this.peek(), '||')) {
+            this.next();
+            const right = this.parseAnd();
+            left = { type: 'or', left, right };
+        }
+        return left;
+    }
+    parseAnd() {
+        let left = this.parseNot();
+        while (this.isWord(this.peek(), 'and') || this.isPunct(this.peek(), '&&')) {
+            this.next();
+            const right = this.parseNot();
+            left = { type: 'and', left, right };
+        }
+        return left;
+    }
+    parseNot() {
+        if (this.isWord(this.peek(), 'not') || this.isPunct(this.peek(), '!')) {
+            this.next();
+            const inner = this.parseNot();
+            return { type: 'not', inner };
+        }
+        return this.parseAtom();
+    }
+    isValidCompareOpStart(tok) {
+        return tokenOpKey(tok) !== null;
+    }
+    parseAtom() {
+        const tok = this.peek();
+        if (this.isPunct(tok, '(')) {
+            this.next();
+            const expr = this.parseExpr();
+            this.expectPunct(')');
+            return expr;
+        }
+        if (tok.type !== 'word') {
+            throw new Error(`Expected a predicate (property comparison, bounds check, relation, or shortcut keyword) but found '${tok.value || 'end of predicate'}' at position ${tok.pos}.`);
+        }
+        const lower = tok.value.toLowerCase();
+        if (lower === 'bounds' || lower === 'rect') {
+            const nextTok = this.peek(1);
+            if (!this.isPunct(nextTok, '.')) {
+                const nextLower = nextTok.type === 'word' ? nextTok.value.toLowerCase() : '';
+                if (BOUNDS_OPS.has(nextLower)) {
+                    return this.parseBoundsPred();
+                }
+                if (!this.isValidCompareOpStart(nextTok)) {
+                    throw new Error(`Unknown operator '${nextTok.value}' after '${tok.value}'. If testing bounds, valid operators are: ${VALID_BOUNDS_OPS_LIST}. ` +
+                        `If comparing a property, use '.' to continue the path (e.g. ${tok.value}.width) followed by a comparison operator.`);
+                }
+                // else: falls through to PropPred below (bare rect/bounds compared as a whole value)
+            }
+        }
+        if (RELATION_KIND[lower]) {
+            return this.parseRelPred();
+        }
+        if (SIZE_OP_KIND[lower]) {
+            return this.parseSizePred();
+        }
+        if (DIR_OP_KIND[lower]) {
+            return this.parseDirPred();
+        }
+        if (lower === 'has-attribute') {
+            return this.parseHasAttrPred();
+        }
+        if (/-of$/i.test(lower)) {
+            throw new Error(`Unknown relation or direction check '${tok.value}'. Valid relations: ${VALID_RELATION_LIST}. Valid direction checks: ${VALID_DIR_OPS_LIST}.`);
+        }
+        if (isOrdinalToken(tok.value)) {
+            const nextTok = this.peek(1);
+            if (!(nextTok.type === 'word' && nextTok.value.toLowerCase() === 'child-of')) {
+                throw new Error(`Ordinal '${tok.value}' must be followed by 'child-of <target>', e.g. '${tok.value} child-of 5'.`);
+            }
+            return this.parseOrdinalChildOf();
+        }
+        if (NULLARY_WORDS.has(lower)) {
+            if (lower === 'text') {
+                const nextTok = this.peek(1);
+                if (this.isValidCompareOpStart(nextTok)) {
+                    return this.parsePropPred();
+                }
+            }
+            this.next();
+            return { type: 'nullary', name: lower };
+        }
+        const nextTok = this.peek(1);
+        const isBoundaryToken = nextTok.type === 'eof' ||
+            this.isWord(nextTok, 'and') ||
+            this.isWord(nextTok, 'or') ||
+            this.isPunct(nextTok, '&&') ||
+            this.isPunct(nextTok, '||') ||
+            this.isPunct(nextTok, ')');
+        if (isBoundaryToken) {
+            throw new Error(`Unknown predicate '${tok.value}'. If you meant a shortcut predicate, valid ones are: ${VALID_NULLARY_LIST}. ` +
+                `If you meant a property comparison, it must be followed by an operator and value, e.g. '${tok.value} = ...'.`);
+        }
+        return this.parsePropPred();
+    }
+    parsePropertyPath() {
+        const first = this.next();
+        if (first.type !== 'word') {
+            throw new Error(`Expected a property name but found '${first.value}' at position ${first.pos}.`);
+        }
+        const path = [first.value];
+        while (this.isPunct(this.peek(), '.')) {
+            this.next();
+            const seg = this.next();
+            if (seg.type !== 'word') {
+                throw new Error(`Expected a property name after '.' but found '${seg.value}' at position ${seg.pos}.`);
+            }
+            path.push(seg.value);
+        }
+        return path;
+    }
+    parsePropPred() {
+        const path = this.parsePropertyPath();
+        const opTok = this.peek();
+        const opKey = tokenOpKey(opTok);
+        if (!opKey) {
+            throw new Error(`Unknown comparison operator '${opTok.value}'. Valid operators: ${VALID_COMPARE_OPS_LIST}.`);
+        }
+        this.next();
+        if (opKey === 'in') {
+            const value = this.parseValueList();
+            return { type: 'prop', path, op: 'in', value };
+        }
+        if (opKey === 'regex') {
+            const value = this.parseRegexValue();
+            return { type: 'prop', path, op: 'regex', value };
+        }
+        const value = this.parseSingleValue();
+        return { type: 'prop', path, op: opKey, value };
+    }
+    parseBareValue() {
+        let text = '';
+        let expectedPos = null;
+        while (true) {
+            const tok = this.peek();
+            if ((tok.type === 'word' || tok.type === 'number') && (expectedPos === null || tok.pos === expectedPos)) {
+                text += tok.value;
+                expectedPos = tok.pos + tok.value.length;
+                this.next();
+            }
+            else {
+                break;
+            }
+        }
+        if (text === '') {
+            const tok = this.peek();
+            throw new Error(`Expected a value but found '${tok.value || 'end of predicate'}' at position ${tok.pos}.`);
+        }
+        return text;
+    }
+    parseSingleValue() {
+        const tok = this.peek();
+        if (tok.type === 'string') {
+            this.next();
+            return tok.value;
+        }
+        if (tok.type === 'regex') {
+            throw new Error(`A /regex/ literal is only valid with the matches/regex/=~ operator, not here (position ${tok.pos}).`);
+        }
+        return this.parseBareValue();
+    }
+    parseValueList() {
+        this.expectPunct('(');
+        const values = [this.parseSingleValue()];
+        while (this.isPunct(this.peek(), ',')) {
+            this.next();
+            values.push(this.parseSingleValue());
+        }
+        this.expectPunct(')');
+        return values;
+    }
+    parseRegexValue() {
+        const tok = this.peek();
+        if (tok.type !== 'regex') {
+            throw new Error(`Expected a /pattern/flags regex literal after 'matches'/'regex'/'=~' but found '${tok.value}' at position ${tok.pos}.`);
+        }
+        this.next();
+        const flags = tok.flags && tok.flags.length > 0 ? tok.flags : 'i';
+        try {
+            return new RegExp(tok.value, flags);
+        }
+        catch (e) {
+            throw new Error(`Invalid regex literal /${tok.value}/${tok.flags ?? ''}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    parseSignedNumber() {
+        const tok = this.next();
+        if (tok.type !== 'number') {
+            throw new Error(`Expected a number but found '${tok.value}' at position ${tok.pos}.`);
+        }
+        return Number(tok.value);
+    }
+    isNodeKeyword(tok) {
+        return tok.type === 'word' && tok.value.toLowerCase() === 'node';
+    }
+    // Assumes the caller already confirmed the current token is the 'node' keyword (via
+    // isNodeKeyword) — this is the one and only way to reference another element by id anywhere
+    // in the grammar (bounds/relation/size/direction targets), freeing up a bare number to mean a
+    // literal value in the targets that accept one (e.g. size targets).
+    parseNodeId() {
+        this.next(); // 'node'
+        const idTok = this.next();
+        if (idTok.type !== 'number') {
+            throw new Error(`Expected a node id (a non-negative integer) after 'node' but found '${idTok.value || 'end of predicate'}' at position ${idTok.pos}.`);
+        }
+        const n = Number(idTok.value);
+        if (n < 0 || !Number.isInteger(n)) {
+            throw new Error(`A node id must be a non-negative integer, got '${idTok.value}' at position ${idTok.pos}.`);
+        }
+        return String(n);
+    }
+    parseBoundsPred() {
+        this.next(); // 'bounds' | 'rect'
+        const opTok = this.next();
+        const opLower = opTok.value.toLowerCase();
+        if (!BOUNDS_OPS.has(opLower)) {
+            throw new Error(`Unknown bounds operator '${opTok.value}'. Valid operators: ${VALID_BOUNDS_OPS_LIST}.`);
+        }
+        const target = this.parseBoundsTarget();
+        return { type: 'bounds', op: BOUNDS_OP_CANON[opLower], target };
+    }
+    parseBoundsTarget() {
+        if (this.isNodeKeyword(this.peek())) {
+            return { type: 'id', id: this.parseNodeId() };
+        }
+        const numbers = [this.parseSignedNumber()];
+        while (this.isPunct(this.peek(), ',')) {
+            this.next();
+            numbers.push(this.parseSignedNumber());
+        }
+        if (numbers.length === 2) {
+            return { type: 'point', x: numbers[0], y: numbers[1] };
+        }
+        if (numbers.length === 4) {
+            const [left, top, width, height] = numbers;
+            return { type: 'rect', rect: { left, top, width, height } };
+        }
+        const hint = numbers.length === 1 ? ` Did you mean 'node ${numbers[0]}'?` : '';
+        throw new Error(`A bounds target must be 'node <id>' (another element), 2 numbers (point 'x,y'), or 4 numbers (rect 'left,top,width,height') — got ${numbers.length} number(s).${hint}`);
+    }
+    parseRelPred() {
+        const kwTok = this.next();
+        const kind = RELATION_KIND[kwTok.value.toLowerCase()];
+        const target = this.parseRelTarget();
+        return { type: 'rel', kind, target };
+    }
+    parseOrdinalChildOf() {
+        const ordTok = this.next();
+        const ordinal = parseOrdinalValue(ordTok.value);
+        this.next(); // 'child-of'
+        const target = this.parseRelTarget();
+        return { type: 'rel', kind: 'nthChild', ordinal, target };
+    }
+    parseRelTarget() {
+        const tok = this.peek();
+        if (this.isNodeKeyword(tok)) {
+            return { type: 'id', id: this.parseNodeId() };
+        }
+        if (tok.type === 'number') {
+            throw new Error(`A relation target must be 'node <id>' to reference another element, or a sub-predicate — found a bare number '${tok.value}' at position ${tok.pos}. Did you mean 'node ${tok.value}'?`);
+        }
+        if (tok.type === 'eof') {
+            throw new Error(`Expected 'node <id>' or a sub-predicate after the relation, but found end of predicate at position ${tok.pos}.`);
+        }
+        // Any other target is a single Atom — this already covers a fully parenthesized
+        // sub-Expr (parseAtom's own "(" Expr ")" case) as well as a bare single-token target
+        // like a nullary predicate, e.g. "ancestor-of text" inside "child-of (ancestor-of text and tagName = BUTTON)".
+        const atom = this.parseAtom();
+        return { type: 'expr', ast: atom };
+    }
+    parseSizePred() {
+        const kwTok = this.next();
+        const kind = SIZE_OP_KIND[kwTok.value.toLowerCase()];
+        const target = this.parseSizeTarget();
+        return { type: 'size', kind, target };
+    }
+    parseSizeTarget() {
+        if (this.isNodeKeyword(this.peek())) {
+            return { type: 'id', id: this.parseNodeId() };
+        }
+        const numbers = [this.parseSignedNumber()];
+        while (this.isPunct(this.peek(), ',')) {
+            this.next();
+            numbers.push(this.parseSignedNumber());
+        }
+        if (numbers.length === 1) {
+            return { type: 'value', value: numbers[0] };
+        }
+        if (numbers.length === 2) {
+            return { type: 'size', width: numbers[0], height: numbers[1] };
+        }
+        if (numbers.length === 4) {
+            const [left, top, width, height] = numbers;
+            return { type: 'rect', rect: { left, top, width, height } };
+        }
+        throw new Error(`A size target must be a single number (a literal value), 2 numbers (size 'width,height'), 4 numbers (rect 'left,top,width,height'), or 'node <id>' (another element) — got ${numbers.length} numbers.`);
+    }
+    parseHasAttrPred() {
+        this.next(); // 'has-attribute'
+        const name = this.parseSingleValue();
+        return { type: 'hasAttr', name };
+    }
+    parseDirPred() {
+        const kwTok = this.next();
+        const kind = DIR_OP_KIND[kwTok.value.toLowerCase()];
+        const target = this.parseDirTarget();
+        return { type: 'dir', kind, target };
+    }
+    parseDirTarget() {
+        if (this.isNodeKeyword(this.peek())) {
+            return { type: 'id', id: this.parseNodeId() };
+        }
+        const numbers = [this.parseSignedNumber()];
+        while (this.isPunct(this.peek(), ',')) {
+            this.next();
+            numbers.push(this.parseSignedNumber());
+        }
+        if (numbers.length === 4) {
+            const [left, top, width, height] = numbers;
+            return { type: 'rect', rect: { left, top, width, height } };
+        }
+        const hint = numbers.length === 1 ? ` Did you mean 'node ${numbers[0]}'?` : '';
+        throw new Error(`A direction target must be 'node <id>' (another element) or 4 numbers (rect 'left,top,width,height') — got ${numbers.length} number(s).${hint}`);
+    }
+}
+export function parsePredicate(source) {
+    if (!source || !source.trim()) {
+        throw new Error('Predicate is empty. A dom-search predicate cannot be blank — see the dom-search predicate grammar documentation for the grammar and examples.');
+    }
+    const tokens = tokenize(source);
+    const parser = new Parser(tokens);
+    return parser.parseTopLevel();
+}
+// ---------------------------------------------------------------------------
+// astNeedsIndex
+// ---------------------------------------------------------------------------
+export function astNeedsIndex(ast) {
+    switch (ast.type) {
+        case 'or':
+        case 'and':
+            return astNeedsIndex(ast.left) || astNeedsIndex(ast.right);
+        case 'not':
+            return astNeedsIndex(ast.inner);
+        case 'rel':
+            return true;
+        case 'bounds':
+        case 'size':
+        case 'dir':
+            return ast.target.type === 'id';
+        case 'prop':
+        case 'nullary':
+        case 'hasAttr':
+            return false;
+    }
+}
+function collectReferencedIds(ast, out) {
+    switch (ast.type) {
+        case 'or':
+        case 'and':
+            collectReferencedIds(ast.left, out);
+            collectReferencedIds(ast.right, out);
+            return;
+        case 'not':
+            collectReferencedIds(ast.inner, out);
+            return;
+        case 'bounds':
+        case 'size':
+        case 'dir':
+            if (ast.target.type === 'id')
+                out.add(ast.target.id);
+            return;
+        case 'rel':
+            if (ast.target.type === 'id')
+                out.add(ast.target.id);
+            else
+                collectReferencedIds(ast.target.ast, out);
+            return;
+        case 'prop':
+        case 'nullary':
+        case 'hasAttr':
+            return;
+    }
+}
+/**
+ * Validates every literal node id referenced anywhere in the predicate (bounds targets and
+ * relation targets, including inside nested chained-relation sub-predicates) against the index,
+ * up front — so a missing id is always caught deterministically, rather than only when tree
+ * traversal happens to reach the specific node/predicate combination that would look it up.
+ */
+function validateReferencedIds(ast, index) {
+    const referenced = new Set();
+    collectReferencedIds(ast, referenced);
+    const missing = [...referenced].filter(id => !index.nodeById.has(id));
+    if (missing.length > 0) {
+        const idList = missing.map(id => `'${id}'`).join(', ');
+        const label = missing.length === 1 ? 'Node id' : 'Node ids';
+        const verb = missing.length === 1 ? 'was' : 'were';
+        throw new Error(`${label} ${idList} referenced in the predicate ${verb} not found in this capture.`);
+    }
+}
+function buildIndex(root) {
+    const nodeById = new Map();
+    const parentById = new Map();
+    const ancestorIds = new Map();
+    function visit(node, parent, ancestors) {
+        if (!node)
+            return;
+        if (Array.isArray(node)) {
+            for (const n of node)
+                visit(n, parent, ancestors);
+            return;
+        }
+        if (!node.tagName || node.tagName.startsWith('#'))
+            return;
+        const id = node.id;
+        if (id != null) {
+            nodeById.set(id, node);
+            parentById.set(id, parent);
+            ancestorIds.set(id, ancestors);
+        }
+        const childAncestors = id != null ? [...ancestors, id] : ancestors;
+        for (const child of node.childNodes ?? []) {
+            visit(child, node, childAncestors);
+        }
+    }
+    visit(root, null, []);
+    return { nodeById, parentById, ancestorIds };
+}
+// ---------------------------------------------------------------------------
+// Node-level helpers (local reimplementations — see file header)
+// ---------------------------------------------------------------------------
+function nodeTextLocal(node) {
+    return (node.childNodes ?? [])
+        .filter((c) => c && c.tagName === '#text')
+        .map((c) => c.text ?? '')
+        .join('');
+}
+function nodeRectLocal(node) {
+    const r = node?.rect;
+    if (!r)
+        return null;
+    const { left, top, width, height } = r;
+    if (typeof left !== 'number' || typeof top !== 'number' || typeof width !== 'number' || typeof height !== 'number')
+        return null;
+    return { left, top, width, height };
+}
+function elementChildrenOf(node) {
+    return (node.childNodes ?? []).filter((c) => c && c.tagName && !c.tagName.startsWith('#'));
+}
+function rectContainsLocal(outer, inner) {
+    return (outer.left <= inner.left &&
+        outer.top <= inner.top &&
+        outer.left + outer.width >= inner.left + inner.width &&
+        outer.top + outer.height >= inner.top + inner.height);
+}
+function rectsIntersectLocal(a, b) {
+    return a.left < b.left + b.width && a.left + a.width > b.left && a.top < b.top + b.height && a.top + a.height > b.top;
+}
+function toStringLoose(v) {
+    if (v == null)
+        return '';
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    return String(v);
+}
+function toNumberLoose(v) {
+    if (typeof v === 'number')
+        return v;
+    if (typeof v !== 'string')
+        return null;
+    const n = parseFloat(v);
+    return Number.isNaN(n) ? null : n;
+}
+function getPropertyValue(node, path) {
+    if (path.length === 1 && path[0] === 'text')
+        return nodeTextLocal(node);
+    let cur = node;
+    for (const seg of path) {
+        if (cur == null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+// ---------------------------------------------------------------------------
+// Evaluator
+// ---------------------------------------------------------------------------
+function evaluateProp(node, ast) {
+    const raw = getPropertyValue(node, ast.path);
+    if (ast.op === 'regex') {
+        return ast.value.test(toStringLoose(raw));
+    }
+    if (ast.op === 'in') {
+        const rawStr = toStringLoose(raw).toLowerCase();
+        return ast.value.some(v => rawStr === v.toLowerCase());
+    }
+    if (ast.op === 'lt' || ast.op === 'lte' || ast.op === 'gt' || ast.op === 'gte') {
+        const a = toNumberLoose(raw);
+        const b = toNumberLoose(ast.value);
+        if (a === null || b === null)
+            return false;
+        if (ast.op === 'lt')
+            return a < b;
+        if (ast.op === 'lte')
+            return a <= b;
+        if (ast.op === 'gt')
+            return a > b;
+        return a >= b;
+    }
+    const rawStr = toStringLoose(raw).toLowerCase();
+    const value = ast.value.toLowerCase();
+    switch (ast.op) {
+        case 'eq':
+            return rawStr === value;
+        case 'neq':
+            return rawStr !== value;
+        case 'startsWith':
+            return rawStr.startsWith(value);
+        case 'endsWith':
+            return rawStr.endsWith(value);
+        case 'contains':
+            return rawStr.includes(value);
+        default:
+            return false;
+    }
+}
+function evaluateNullary(name, node) {
+    const tagName = (node.tagName ?? '').toUpperCase();
+    const attrs = node.attributes ?? {};
+    const style = node.style ?? {};
+    switch (name) {
+        case 'text':
+            return nodeTextLocal(node).trim().length > 0;
+        case 'image': {
+            if (tagName === 'IMG' || tagName === 'SVG' || tagName === 'PICTURE')
+                return true;
+            const bg = style['background-image'];
+            return !!bg && bg !== 'none';
+        }
+        case 'gif':
+            return tagName === 'IMG' && /\.gif$/i.test(attrs.src ?? '');
+        case 'logo': {
+            const hay = [attrs.class, attrs.id, attrs.alt].filter(Boolean).join(' ').toLowerCase();
+            return hay.includes('logo');
+        }
+        case 'link':
+            return tagName === 'A';
+        case 'button': {
+            if (tagName === 'BUTTON')
+                return true;
+            if (tagName === 'INPUT') {
+                const type = (attrs.type ?? '').toLowerCase();
+                if (type === 'button' || type === 'submit' || type === 'reset')
+                    return true;
+            }
+            return (attrs.role ?? '').toLowerCase() === 'button';
+        }
+        case 'heading':
+            return /^H[1-6]$/.test(tagName);
+        case 'hidden':
+            return !isVisible(node);
+        case 'visible':
+            return isVisible(node);
+        case 'empty':
+            return nodeTextLocal(node).trim().length === 0 && elementChildrenOf(node).length === 0;
+        case 'true':
+            return true;
+        case 'false':
+            return false;
+        default:
+            return false;
+    }
+}
+function evaluateHasAttr(node, name) {
+    const attrs = node.attributes ?? {};
+    const target = name.toLowerCase();
+    return Object.keys(attrs).some(k => k.toLowerCase() === target);
+}
+function resolveBoundsTarget(target, index) {
+    if (target.type === 'point')
+        return { left: target.x, top: target.y, width: 0, height: 0 };
+    if (target.type === 'rect')
+        return target.rect;
+    // Referenced ids are validated up front in searchDom, so this lookup is guaranteed to succeed.
+    return nodeRectLocal(index.nodeById.get(target.id));
+}
+function evaluateBounds(node, ast, index) {
+    const r = nodeRectLocal(node);
+    if (!r)
+        return false;
+    const targetRect = resolveBoundsTarget(ast.target, index);
+    if (!targetRect)
+        return false;
+    switch (ast.op) {
+        case 'contains':
+            return rectContainsLocal(r, targetRect);
+        case 'intersects':
+            return rectsIntersectLocal(r, targetRect);
+        case 'containedBy':
+            return rectContainsLocal(targetRect, r);
+    }
+}
+function scalarFromWH(width, height, kind) {
+    switch (kind) {
+        case 'larger':
+        case 'smaller':
+            return width * height;
+        case 'wider':
+        case 'narrower':
+            return width;
+        case 'taller':
+        case 'shorter':
+            return height;
+    }
+}
+function resolveSizeTargetScalar(target, kind, index) {
+    if (target.type === 'value')
+        return target.value;
+    if (target.type === 'size')
+        return scalarFromWH(target.width, target.height, kind);
+    if (target.type === 'rect')
+        return scalarFromWH(target.rect.width, target.rect.height, kind);
+    // Referenced ids are validated up front in searchDom.
+    const r = nodeRectLocal(index.nodeById.get(target.id));
+    return r ? scalarFromWH(r.width, r.height, kind) : null;
+}
+function evaluateSizePred(node, ast, index) {
+    const r = nodeRectLocal(node);
+    if (!r)
+        return false;
+    const selfScalar = scalarFromWH(r.width, r.height, ast.kind);
+    const targetScalar = resolveSizeTargetScalar(ast.target, ast.kind, index);
+    if (targetScalar === null)
+        return false;
+    switch (ast.kind) {
+        case 'larger':
+        case 'wider':
+        case 'taller':
+            return selfScalar > targetScalar;
+        case 'smaller':
+        case 'narrower':
+        case 'shorter':
+            return selfScalar < targetScalar;
+    }
+}
+function resolveDirTargetRect(target, index) {
+    if (target.type === 'rect')
+        return target.rect;
+    // Referenced ids are validated up front in searchDom.
+    return nodeRectLocal(index.nodeById.get(target.id));
+}
+function evaluateDirPred(node, ast, index) {
+    const r = nodeRectLocal(node);
+    if (!r)
+        return false;
+    const t = resolveDirTargetRect(ast.target, index);
+    if (!t)
+        return false;
+    switch (ast.kind) {
+        case 'above':
+            return r.top + r.height <= t.top;
+        case 'below':
+            return r.top >= t.top + t.height;
+        case 'leftOf':
+            return r.left + r.width <= t.left;
+        case 'rightOf':
+            return r.left >= t.left + t.width;
+    }
+}
+function resolveRelTargetMatch(candidateNode, target, index) {
+    if (target.type === 'id') {
+        // Referenced ids are validated up front in searchDom, so no existence check needed here.
+        return candidateNode.id === target.id;
+    }
+    return evaluateNode(candidateNode, target.ast, index);
+}
+function someDescendant(node, predicate) {
+    for (const child of elementChildrenOf(node)) {
+        if (predicate(child))
+            return true;
+        if (someDescendant(child, predicate))
+            return true;
+    }
+    return false;
+}
+function evaluateRel(node, ast, index) {
+    const nodeId = node.id;
+    if (ast.kind === 'child' || ast.kind === 'nthChild') {
+        const parent = index.parentById.get(nodeId);
+        if (!parent)
+            return false;
+        if (ast.kind === 'nthChild') {
+            const siblings = elementChildrenOf(parent);
+            const idx = ast.ordinal - 1;
+            if (idx < 0 || idx >= siblings.length)
+                return false;
+            if (siblings[idx].id !== nodeId)
+                return false;
+        }
+        return resolveRelTargetMatch(parent, ast.target, index);
+    }
+    if (ast.kind === 'parent') {
+        return elementChildrenOf(node).some(child => resolveRelTargetMatch(child, ast.target, index));
+    }
+    if (ast.kind === 'sibling') {
+        const parent = index.parentById.get(nodeId);
+        if (!parent)
+            return false;
+        return elementChildrenOf(parent).some(sib => {
+            const sibId = sib.id;
+            if (sibId === nodeId)
+                return false;
+            return resolveRelTargetMatch(sib, ast.target, index);
+        });
+    }
+    if (ast.kind === 'ancestor') {
+        return someDescendant(node, d => resolveRelTargetMatch(d, ast.target, index));
+    }
+    if (ast.kind === 'descendant') {
+        const chain = index.ancestorIds.get(nodeId) ?? [];
+        return chain.some(aid => {
+            const a = index.nodeById.get(aid);
+            return a ? resolveRelTargetMatch(a, ast.target, index) : false;
+        });
+    }
+    return false;
+}
+function evaluateNode(node, ast, index) {
+    switch (ast.type) {
+        case 'or':
+            return evaluateNode(node, ast.left, index) || evaluateNode(node, ast.right, index);
+        case 'and':
+            return evaluateNode(node, ast.left, index) && evaluateNode(node, ast.right, index);
+        case 'not':
+            return !evaluateNode(node, ast.inner, index);
+        case 'bounds':
+            return evaluateBounds(node, ast, index);
+        case 'rel':
+            return evaluateRel(node, ast, index);
+        case 'size':
+            return evaluateSizePred(node, ast, index);
+        case 'dir':
+            return evaluateDirPred(node, ast, index);
+        case 'prop':
+            return evaluateProp(node, ast);
+        case 'nullary':
+            return evaluateNullary(ast.name, node);
+        case 'hasAttr':
+            return evaluateHasAttr(node, ast.name);
+    }
+}
+// ---------------------------------------------------------------------------
+// searchDom
+// ---------------------------------------------------------------------------
+/**
+ * Searches a DOM capture for elements matching a boolean predicate. See `llm-docs/dom-search.md`
+ * in this package (shipped in the tarball) for the full predicate language documentation (grammar,
+ * operators, examples) — that file is the canonical, copy-paste-friendly source; don't re-describe
+ * the grammar here or anywhere else, keep it in sync by editing it and copying it where it's
+ * needed instead.
+ *
+ * @param domCaptureJson Raw JSON text of a DOM capture file (as written by eyes-inspect's `dom` command) — a single node, or an array of nodes.
+ * @param predicateSource The predicate string described in `llm-docs/dom-search.md`.
+ * @returns One line per matching element, most indented lines the deepest — each line is that element's own properties (minus `childNodes`) as JSON, with a trailing `# <text>` comment when it has non-empty text.
+ */
+export function searchDom(domCaptureJson, predicateSource) {
+    const ast = parsePredicate(predicateSource);
+    const root = JSON.parse(domCaptureJson);
+    const index = astNeedsIndex(ast) ? buildIndex(root) : undefined;
+    if (index)
+        validateReferencedIds(ast, index);
+    const lines = [];
+    function walk(node, depth) {
+        if (!node)
+            return;
+        if (Array.isArray(node)) {
+            for (const n of node)
+                walk(n, depth);
+            return;
+        }
+        if (!node.tagName || node.tagName.startsWith('#'))
+            return;
+        if (evaluateNode(node, ast, index)) {
+            const { childNodes: _childNodes, ...rest } = node;
+            // Collapse whitespace (including any literal newlines from the raw text) so a match with
+            // multi-line text still renders as exactly one output line, matching the documented
+            // one-line-per-match format. Only the trailing annotation is collapsed — the underlying
+            // `text` property used for predicate matching keeps the raw, uncollapsed content.
+            const displayText = nodeTextLocal(node).replace(/\s+/g, ' ').trim();
+            const suffix = displayText.length > 0 ? ` # ${displayText}` : '';
+            lines.push('  '.repeat(depth) + JSON.stringify(rest) + suffix);
+        }
+        for (const child of node.childNodes ?? []) {
+            walk(child, depth + 1);
+        }
+    }
+    walk(root, 0);
+    return lines.join('\n');
+}