@terminai/core 0.21.0

package/dist/src/gui/selectors/matcher.js

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * Portions Copyright 2025 TerminaI Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function matchSelector(element, selector) {
+    // 1. Check Prefix compatibility (optional optimization)
+    // For 'uia:', we might define that it MUST have platformIds.automationId?
+    // For v1 let's be permissive unless 'atspi' is requested on Windows etc,
+    // but here we just have the element, so we check conditions.
+    if (selector.type !== 'selector')
+        return { matches: false, confidence: 0 };
+    let totalConfidence = 1.0;
+    let hasStrongIdentity = false;
+    for (const cond of selector.conditions) {
+        const result = matchCondition(element, cond);
+        if (!result.matches) {
+            return { matches: false, confidence: 0 };
+        }
+        // Accumulate confidence
+        // If we match on stable ID, confidence is high.
+        // If we match on name, it's medium.
+        if (result.isStrongIdentity)
+            hasStrongIdentity = true;
+    }
+    // Base confidence adjustments
+    if (hasStrongIdentity) {
+        totalConfidence = 1.0;
+    }
+    else {
+        // Name only? 0.8
+        totalConfidence = 0.8;
+    }
+    // OCR prefix might lower confidence in future
+    if (selector.prefix === 'ocr') {
+        totalConfidence *= 0.7;
+    }
+    return { matches: true, confidence: totalConfidence };
+}
+function matchCondition(element, cond) {
+    if (cond.type === 'boolean') {
+        const states = element.states || {};
+        let actual = false;
+        if (cond.name === 'enabled')
+            actual = states.enabled ?? true; // default enabled?
+        if (cond.name === 'visible')
+            actual = true; // In snapshot, assumed visible usually
+        // TODO: better state mapping from ElementNode
+        // For now, if state is missing, we assume false unless 'enabled' (default true-ish)
+        if (cond.name === 'enabled' && element.states?.enabled === undefined)
+            actual = true;
+        if (cond.name === 'focused')
+            actual = states.focused || false;
+        return { matches: actual === cond.value, isStrongIdentity: false };
+    }
+    if (cond.type === 'attribute') {
+        const val = getAttributeValue(element, cond.name);
+        if (val === undefined)
+            return { matches: false, isStrongIdentity: false };
+        const matches = checkOperator(String(val), String(cond.value), cond.operator);
+        // Determine strength
+        const strongAttrs = [
+            'automationId',
+            'runtimeId',
+            'legacyId',
+            'atspiPath',
+            'axId',
+            'sapId',
+        ];
+        const isStrong = strongAttrs.includes(cond.name);
+        return { matches, isStrongIdentity: isStrong };
+    }
+    return { matches: false, isStrongIdentity: false };
+}
+function getAttributeValue(element, attr) {
+    switch (attr) {
+        case 'role':
+            return element.role;
+        case 'name':
+            return element.name;
+        case 'value':
+            return element.value;
+        case 'automationId':
+            return element.platformIds?.automationId;
+        case 'runtimeId':
+            return element.platformIds?.runtimeId;
+        case 'legacyId':
+            return element.platformIds?.legacyId;
+        case 'atspiPath':
+            return element.platformIds?.atspiPath;
+        // ... add others
+        // ... add others
+        default:
+            return undefined;
+    }
+}
+function checkOperator(actual, expected, op) {
+    // Case insensitive for most things? Architecture says:
+    // "role" case-insensitive normalized
+    // "name" exact + case-insensitive contains usually
+    // For v1 implementation:
+    const a = actual.toLowerCase();
+    const b = expected.toLowerCase();
+    switch (op) {
+        case '=':
+            return a === b;
+        case '~=':
+            return a.includes(b);
+        case '^=':
+            return a.startsWith(b);
+        case '$=':
+            return a.endsWith(b);
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=matcher.js.map

package/dist/src/gui/selectors/matcher.js.map

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

package/dist/src/gui/selectors/parser.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * Portions Copyright 2025 TerminaI Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Selector Parser (v1)
+ *
+ * Parses a string selector into a SelectorNode AST.
+ * Supports:
+ * - Prefixes: any:, uia:, atspi:, win32:, etc.
+ * - Conditions: role=X, name="Y", enabled=true
+ * - Operators: &&
+ * - Combinators: >> (descendant)
+ * - Fallback: ??
+ *
+ * Example: `uia:role=Button && name="Submit" ?? ocr:"Submit"`
+ */
+import type { SelectorNode } from './ast.js';
+export declare class SelectorParseError extends Error {
+    position: number;
+    hint?: string;
+    constructor(message: string, position: number, hint?: string);
+}
+export declare function parseSelector(input: string): SelectorNode;

package/dist/src/gui/selectors/parser.js

@@ -0,0 +1,235 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * Portions Copyright 2025 TerminaI Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class SelectorParseError extends Error {
+    position;
+    hint;
+    constructor(message, position, hint) {
+        super(`Selector parse error at index ${position}: ${message}`);
+        this.position = position;
+        this.hint = hint;
+    }
+}
+/**
+ * Detect common CSS selector patterns and return a helpful hint.
+ */
+function detectCssSelectorHint(input) {
+    const cssPatterns = [
+        /^\.[a-zA-Z_-]/, // .class
+        /^#[a-zA-Z_-]/, // #id
+        /^[a-z]+\s*>/, // tag >
+        /\[.*=.*\]/, // [attr=value]
+    ];
+    for (const pattern of cssPatterns) {
+        if (pattern.test(input.trim())) {
+            return 'This looks like a CSS selector. UI selectors use a different syntax: name:"...", role=..., enabled=true, etc.';
+        }
+    }
+    return undefined;
+}
+export function parseSelector(input) {
+    const hint = detectCssSelectorHint(input);
+    const parser = new Parser(input, hint);
+    return parser.parse();
+}
+class Parser {
+    input;
+    hint;
+    pos = 0;
+    len;
+    constructor(input, hint) {
+        this.input = input;
+        this.hint = hint;
+        this.len = input.length;
+    }
+    parse() {
+        // Top level: Parse fallback chain (A ?? B)
+        const left = this.parseChain();
+        this.skipWhitespace();
+        if (this.match('??')) {
+            const right = this.parse(); // Recurse for right-associativity
+            left.fallback = right;
+        }
+        return left;
+    }
+    parseChain() {
+        // Parse combinator chain (A >> B)
+        const left = this.parseSingleSelector();
+        this.skipWhitespace();
+        while (this.match('>>')) {
+            // For v1 we only really support descendant '>>' as primary combinator
+            // The AST supports 'right-of' etc but we parse '>>' as descendant
+            const right = this.parseSingleSelector();
+            // Link as 'next'
+            // We need to walk to the end of the current 'left's 'next' chain if it exists
+            // But parseSingleSelector returns a single node (maybe with its own next? no, parseSingle is one segment)
+            // Wait, parseSingleSelector creates one node.
+            // If we have A >> B >> C
+            // left = A
+            // match >>
+            // right = B
+            // A.next = { combinator: 'descendant', node: B }
+            // Loop: match >>
+            // right = C
+            // But where to attach C? B.next.
+            // Actually simpler: recursive structure handles this naturally usually,
+            // but let's stick to iterative for the chain to keep it flat-ish or handle attaching to tail.
+            // Let's do it recursively: A >> (Rest)
+            // Implementation detail: The AST 'next' is on the SelectorNode.
+            // So A.next -> B.
+            // If we do iterative:
+            let tail = left;
+            while (tail.next) {
+                tail = tail.next.node;
+            }
+            tail.next = { combinator: 'descendant', node: right };
+            this.skipWhitespace();
+        }
+        return left;
+    }
+    parseSingleSelector() {
+        this.skipWhitespace();
+        // 1. Parse Prefix (optional, default 'any')
+        let prefix = 'any';
+        const prefixMatch = this.input.slice(this.pos).match(/^([a-z0-9]+):/i);
+        if (prefixMatch) {
+            prefix = prefixMatch[1].toLowerCase();
+            this.pos += prefixMatch[0].length;
+        }
+        // 2. Parse Conditions
+        const conditions = [];
+        // If we just have `ocr:"Submit"`, that's a shortcut for `ocr:text="Submit"` or similar?
+        // The spec says `ocr:"Submit"` is possible.
+        // Let's handle generic `key=value` pairs separated by `&&`.
+        // Special case: if prefix is 'ocr' and next token is a string literal, implies text match?
+        // Let's stick to explicit `key=value` for now, or the architecture example `ocr:"Submit"` -> treating as name/text.
+        // Allow parsing one string literal as an implicit "name" or "text" condition if format matches
+        this.skipWhitespace();
+        if (this.peek() === '"' || this.peek() === "'") {
+            // Implicit name/text match
+            const val = this.parseString();
+            conditions.push({
+                type: 'attribute',
+                name: 'name',
+                operator: '=',
+                value: val,
+            });
+        }
+        else {
+            // Parse Key=Value && ...
+            do {
+                this.skipWhitespace();
+                const condition = this.parseCondition();
+                conditions.push(condition);
+                this.skipWhitespace();
+            } while (this.match('&&'));
+        }
+        return {
+            type: 'selector',
+            prefix,
+            conditions,
+        };
+    }
+    parseCondition() {
+        // key op value
+        const key = this.readIdentifier();
+        this.skipWhitespace();
+        let op = '=';
+        if (this.match('~='))
+            op = '~=';
+        else if (this.match('^='))
+            op = '^=';
+        else if (this.match('$='))
+            op = '$=';
+        else if (this.match('='))
+            op = '=';
+        else
+            throw new SelectorParseError('Expected operator (=, ~=, ^=, $=)', this.pos, this.hint);
+        this.skipWhitespace();
+        const value = this.parseValue();
+        // Helper for boolean shortcuts
+        if (key === 'enabled' || key === 'visible' || key === 'focused') {
+            if (typeof value !== 'boolean') {
+                // Try to coerce generic strings "true"/"false" if parsed as string
+                if (value === 'true')
+                    return { type: 'boolean', name: key, value: true };
+                if (value === 'false')
+                    return { type: 'boolean', name: key, value: false };
+                throw new SelectorParseError(`${key} requires boolean value`, this.pos, this.hint);
+            }
+            return { type: 'boolean', name: key, value };
+        }
+        return {
+            type: 'attribute',
+            name: key,
+            operator: op,
+            value,
+        };
+    }
+    parseValue() {
+        if (this.peek() === '"' || this.peek() === "'") {
+            return this.parseString();
+        }
+        const start = this.pos;
+        // Read until whitespace or specialized char
+        while (this.pos < this.len && !/[\s&>?)\]]/.test(this.input[this.pos])) {
+            this.pos++;
+        }
+        const raw = this.input.slice(start, this.pos);
+        if (raw === 'true')
+            return true;
+        if (raw === 'false')
+            return false;
+        const num = Number(raw);
+        if (!isNaN(num) && raw.trim() !== '')
+            return num;
+        return raw;
+    }
+    parseString() {
+        const quote = this.input[this.pos];
+        this.pos++; // skip quote
+        let res = '';
+        while (this.pos < this.len) {
+            const char = this.input[this.pos];
+            if (char === '\\') {
+                this.pos++;
+                res += this.input[this.pos];
+            }
+            else if (char === quote) {
+                this.pos++;
+                return res;
+            }
+            else {
+                res += char;
+            }
+            this.pos++;
+        }
+        throw new SelectorParseError('Unterminated string', this.pos, this.hint);
+    }
+    readIdentifier() {
+        const start = this.pos;
+        while (this.pos < this.len && /[a-zA-Z0-9_-]/.test(this.input[this.pos])) {
+            this.pos++;
+        }
+        return this.input.slice(start, this.pos);
+    }
+    skipWhitespace() {
+        while (this.pos < this.len && /\s/.test(this.input[this.pos])) {
+            this.pos++;
+        }
+    }
+    peek() {
+        return this.input[this.pos];
+    }
+    match(str) {
+        if (this.input.startsWith(str, this.pos)) {
+            this.pos += str.length;
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/src/gui/selectors/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../../../src/gui/selectors/parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAKlC;IAJF,IAAI,CAAU;IAErB,YACE,OAAe,EACR,QAAgB,EACvB,IAAa;QAEb,KAAK,CAAC,iCAAiC,QAAQ,KAAK,OAAO,EAAE,CAAC,CAAC;QAHxD,aAAQ,GAAR,QAAQ,CAAQ;QAIvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;GAEG;AACH,SAAS,qBAAqB,CAAC,KAAa;IAC1C,MAAM,WAAW,GAAG;QAClB,eAAe,EAAE,SAAS;QAC1B,cAAc,EAAE,MAAM;QACtB,aAAa,EAAE,QAAQ;QACvB,WAAW,EAAE,eAAe;KAC7B,CAAC;IACF,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;QAClC,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC/B,OAAO,+GAA+G,CAAC;QACzH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,IAAI,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,MAAM;IAKA;IACA;IALF,GAAG,GAAG,CAAC,CAAC;IACR,GAAG,CAAS;IAEpB,YACU,KAAa,EACb,IAAa;QADb,UAAK,GAAL,KAAK,CAAQ;QACb,SAAI,GAAJ,IAAI,CAAS;QAErB,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED,KAAK;QACH,2CAA2C;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAE/B,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,kCAAkC;YAC9D,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,UAAU;QAChB,kCAAkC;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAExC,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,sEAAsE;YACtE,kEAAkE;YAClE,MAAM,KAAK,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAEzC,iBAAiB;YACjB,8EAA8E;YAC9E,0GAA0G;YAE1G,8CAA8C;YAC9C,yBAAyB;YACzB,WAAW;YACX,WAAW;YACX,YAAY;YACZ,iDAAiD;YACjD,iBAAiB;YACjB,YAAY;YACZ,iCAAiC;YAEjC,wEAAwE;YACxE,8FAA8F;YAE9F,uCAAuC;YACvC,gEAAgE;YAChE,kBAAkB;YAElB,sBAAsB;YACtB,IAAI,IAAI,GAAG,IAAI,CAAC;YAChB,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;gBACjB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACxB,CAAC;YACD,IAAI,CAAC,IAAI,GAAG,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YAEtD,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,mBAAmB;QACzB,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,4CAA4C;QAC5C,IAAI,MAAM,GAAmB,KAAK,CAAC;QACnC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACvE,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,EAAoB,CAAC;YACxD,IAAI,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACpC,CAAC;QAED,sBAAsB;QACtB,MAAM,UAAU,GAAoB,EAAE,CAAC;QAEvC,wFAAwF;QACxF,4CAA4C;QAC5C,4DAA4D;QAC5D,2FAA2F;QAC3F,oHAAoH;QAEpH,+FAA+F;QAC/F,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAC/C,2BAA2B;YAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAC/B,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,MAAM;gBACZ,QAAQ,EAAE,GAAG;gBACb,KAAK,EAAE,GAAG;aACX,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,yBAAyB;YACzB,GAAG,CAAC;gBACF,IAAI,CAAC,cAAc,EAAE,CAAC;gBACtB,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;gBACxC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC3B,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;QAC7B,CAAC;QAED,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,MAAM;YACN,UAAU;SACX,CAAC;IACJ,CAAC;IAEO,cAAc;QACpB,eAAe;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAClC,IAAI,CAAC,cAAc,EAAE,CAAC;QAEtB,IAAI,EAAE,GAAG,GAAG,CAAC;QACb,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,EAAE,GAAG,IAAI,CAAC;aAC3B,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,EAAE,GAAG,IAAI,CAAC;aAChC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,EAAE,GAAG,IAAI,CAAC;aAChC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;YAAE,EAAE,GAAG,GAAG,CAAC;;YAEjC,MAAM,IAAI,kBAAkB,CAC1B,mCAAmC,EACnC,IAAI,CAAC,GAAG,EACR,IAAI,CAAC,IAAI,CACV,CAAC;QAEJ,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAEhC,+BAA+B;QAC/B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAChE,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC/B,mEAAmE;gBACnE,IAAI,KAAK,KAAK,MAAM;oBAClB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;gBACrD,IAAI,KAAK,KAAK,OAAO;oBACnB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBACtD,MAAM,IAAI,kBAAkB,CAC1B,GAAG,GAAG,yBAAyB,EAC/B,IAAI,CAAC,GAAG,EACR,IAAI,CAAC,IAAI,CACV,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAC/C,CAAC;QAED,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,GAAG;YACT,QAAQ,EAAE,EAA8B;YACxC,KAAK;SACN,CAAC;IACJ,CAAC;IAEO,UAAU;QAChB,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAC/C,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;QAC5B,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC;QACvB,4CAA4C;QAC5C,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACvE,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QAE9C,IAAI,GAAG,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QAChC,IAAI,GAAG,KAAK,OAAO;YAAE,OAAO,KAAK,CAAC;QAClC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,GAAG,CAAC;QAEjD,OAAO,GAAG,CAAC;IACb,CAAC;IAEO,WAAW;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,aAAa;QACzB,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,IAAI,CAAC,GAAG,EAAE,CAAC;gBACX,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC;iBAAM,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;gBAC1B,IAAI,CAAC,GAAG,EAAE,CAAC;gBACX,OAAO,GAAG,CAAC;YACb,CAAC;iBAAM,CAAC;gBACN,GAAG,IAAI,IAAI,CAAC;YACd,CAAC;YACD,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;QACD,MAAM,IAAI,kBAAkB,CAAC,qBAAqB,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3E,CAAC;IAEO,cAAc;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC;QACvB,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACzE,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAEO,cAAc;QACpB,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC9D,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC;IAEO,IAAI;QACV,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAEO,KAAK,CAAC,GAAW;QACvB,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/src/gui/selectors/resolve.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * Portions Copyright 2025 TerminaI Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Selector Resolver
+ *
+ * Resolves a selector string or AST against a VisualDOMSnapshot tree.
+ */
+import type { ElementNode, VisualDOMSnapshot } from '../protocol/types.js';
+import type { SelectorNode } from './ast.js';
+export interface ResolvedElement {
+    node: ElementNode;
+    confidence: number;
+}
+export declare function resolveSelector(snapshot: VisualDOMSnapshot, selector: string | SelectorNode): ResolvedElement[];

package/dist/src/gui/selectors/resolve.js

@@ -0,0 +1,74 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * Portions Copyright 2025 TerminaI Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { parseSelector } from './parser.js';
+import { matchSelector } from './matcher.js';
+export function resolveSelector(snapshot, selector) {
+    const root = snapshot.tree;
+    if (!root)
+        return [];
+    const ast = typeof selector === 'string' ? parseSelector(selector) : selector;
+    return resolveNode(root, ast);
+}
+function resolveNode(scope, ast) {
+    // Handle Fallback (A ?? B)
+    if (ast.fallback) {
+        // Break the fallback chain: verify if A matches anything
+        // We need to clone the AST without the fallback to test 'A'
+        const primaryAst = { ...ast, fallback: undefined };
+        const primaryMatches = resolveSingleChain(scope, primaryAst);
+        if (primaryMatches.length > 0) {
+            return primaryMatches;
+        }
+        // Fallback
+        return resolveNode(scope, ast.fallback);
+    }
+    return resolveSingleChain(scope, ast);
+}
+function resolveSingleChain(scope, ast) {
+    // Find matches for the current node first (DFS)
+    const matches = findMatchesInSubtree(scope, ast);
+    // If there's a next node in the chain (>>), we must resolve it
+    // scoped to the subtrees of the matches we found.
+    if (ast.next) {
+        const nextAst = ast.next.node;
+        if (ast.next.combinator === 'descendant') {
+            const chainedMatches = [];
+            for (const match of matches) {
+                if (!match.node.children)
+                    continue;
+                for (const child of match.node.children) {
+                    const subMatches = resolveNode(child, nextAst);
+                    chainedMatches.push(...subMatches);
+                }
+            }
+            return chainedMatches;
+        }
+        // TODO: implement other combinators if needed
+    }
+    return matches;
+}
+function findMatchesInSubtree(root, selector) {
+    const results = [];
+    // DFS
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        const result = matchSelector(node, selector);
+        if (result.matches) {
+            results.push({ node, confidence: result.confidence });
+        }
+        if (node.children) {
+            // Push children in reverse for natural order?
+            // Actually standard stack is fine, we just want to find all.
+            for (let i = node.children.length - 1; i >= 0; i--) {
+                stack.push(node.children[i]);
+            }
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/src/gui/selectors/resolve.js.map

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

package/dist/src/gui/service/DesktopAutomationService.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * Portions Copyright 2025 TerminaI Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { DesktopDriver } from '../drivers/types.js';
+import type { VisualDOMSnapshot, UiActionResult, DriverCapabilities, DriverDescriptor, UiDiagnosticsReport } from '../protocol/types.js';
+import type { UiClickArgs, UiTypeArgs, UiQueryArgs, UiSnapshotArgs, UiKeyArgs, UiScrollArgs, UiFocusArgs, UiClickXyArgs, UiWaitArgs, UiAssertArgs, UiDiagnoseArgs } from '../protocol/schemas.js';
+export declare class DesktopAutomationService {
+    private static instance;
+    private driver;
+    private lastSnapshot?;
+    private lastSnapshotTime;
+    private static readonly SNAPSHOT_TTL_MS;
+    private enabled;
+    private driverDescriptor?;
+    private actionTimestamps;
+    private constructor();
+    static setDriverForTest(driver: DesktopDriver): void;
+    static getInstance(): DesktopAutomationService;
+    setEnabled(enabled: boolean): void;
+    getCapabilities(): Promise<DriverCapabilities>;
+    getDriverDescriptor(): Promise<DriverDescriptor>;
+    private ensureConnected;
+    private ensureCapability;
+    snapshot(args: UiSnapshotArgs): Promise<VisualDOMSnapshot>;
+    private graftNode;
+    query(args: UiQueryArgs): Promise<UiActionResult>;
+    click(args: UiClickArgs): Promise<UiActionResult>;
+    type(args: UiTypeArgs): Promise<UiActionResult>;
+    key(args: UiKeyArgs): Promise<UiActionResult>;
+    scroll(args: UiScrollArgs): Promise<UiActionResult>;
+    focus(args: UiFocusArgs): Promise<UiActionResult>;
+    clickXy(args: UiClickXyArgs): Promise<UiActionResult>;
+    waitFor(args: UiWaitArgs, signal?: AbortSignal): Promise<UiActionResult>;
+    assert(args: UiAssertArgs): Promise<UiActionResult>;
+    private safeResolve;
+    private enforceActionRateLimit;
+    private buildBoundedSnapshotArgs;
+    private applySnapshotBounds;
+    private buildResultWithEvidence;
+    private ensureSnapshot;
+    private resolveTargetForAction;
+    diagnose(args?: UiDiagnoseArgs): Promise<UiDiagnosticsReport>;
+}