@xenon-device-management/xenon 2.14.0 → 2.16.0

package/lib/src/services/healing/HealingOrchestrator.js

@@ -1,43 +1,10 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
@@ -54,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HealingOrchestrator = void 0;
+exports.HealingOrchestrator = exports.LOCAL_HEALING_TIERS = void 0;
 exports.filterProvidersByTier = filterProvidersByTier;
 exports.coerceHealingTiersCap = coerceHealingTiersCap;
 exports.healingTiersFromCaps = healingTiersFromCaps;
@@ -67,6 +34,7 @@ const VisualAiHealingProvider_1 = require("./VisualAiHealingProvider");
 const LlmHealingProvider_1 = require("./LlmHealingProvider");
 const HealEtalonService_1 = require("./HealEtalonService");
 const ResilioTreeHealingProvider_1 = require("./ResilioTreeHealingProvider");
+const resilioPath_1 = require("./resilioPath");
 const HealingMetrics_1 = require("./HealingMetrics");
 const attributes_1 = require("../telemetry/attributes");
 const xenonOptions_1 = require("../session/xenonOptions");
@@ -86,24 +54,48 @@ function filterProvidersByTier(providers, allowedTiers) {
     const allowed = new Set(allowedTiers);
     return providers.filter((_, index) => allowed.has(index + 1));
 }
+// The tiers that run on this server: Resilio, Fuzzy XML and OCR. Visual AI (4)
+// and the LLM (5) send the screenshot and the page source to the AI provider.
+exports.LOCAL_HEALING_TIERS = [1, 2, 3];
+const isHealingTierList = (raw) => Array.isArray(raw) && raw.every((t) => Number.isInteger(t) && t >= 1 && t <= 5);
 // Coerce the raw xe:options.healingTiers capability value into the
-// allowedTiers argument for attemptHealing. Fail-open contract (Phase 2a
-// review fix): a malformed cap must RUN ALL tiers, never silently disable
-// healing. Pre-fix, an all-non-numeric array (e.g. ["1","2"]) filtered to []
-// which filterProvidersByTier turned into "no providers" — healing silently
-// off. Now any coercion that yields no numeric tiers (non-array, all-non-
-// numeric, or an explicitly-empty []) returns undefined → run all tiers.
-// The cap is meant to restrict healing, not disable it, so an explicit []
-// opting out of healing entirely is deliberately NOT supported.
+// allowedTiers argument for attemptHealing. The value is a privacy control (a
+// session leaves out 4 and 5 to keep its screen away from the AI provider), so
+// one that can't be read fails closed for the AI tiers and open for the rest:
+// - not set (or null): every tier (undefined);
+// - a list of tier numbers 1 to 5: exactly those, and [] none;
+// - anything else ("1,2", ["1","2"], [1, 6], ...): LOCAL_HEALING_TIERS.
+// Through 2.14 [], or a value that wasn't a list or had no numbers in it, ran
+// every tier, the AI ones included; a list that held some numbers ran those
+// and skipped the rest ([1, 6] ran tier 1, [6] none).
 function coerceHealingTiersCap(raw) {
-    const nums = Array.isArray(raw) ? raw.filter((t) => typeof t === 'number') : undefined;
-    return nums && nums.length === 0 ? undefined : nums;
+    if (raw === undefined || raw === null)
+        return undefined;
+    return isHealingTierList(raw) ? [...raw] : [...exports.LOCAL_HEALING_TIERS];
 }
 // The allowedTiers a session asked for, read from its capabilities (one flat
-// map, e.g. the session response): xe:options.healingTiers, or the
-// xenon:options alias's, coerced as above.
+// map: the session's driver's caps): xe:options.healingTiers, or the
+// xenon:options alias's, coerced as above. A namespace that isn't an object
+// can't be read either: xenonOptionsIn skips it, which would run every tier.
+// `unreadable` says what couldn't be read, for the log.
 function healingTiersFromCaps(caps) {
-    return coerceHealingTiersCap((0, xenonOptions_1.xenonOptionsIn)(caps).healingTiers);
+    for (const namespace of xenonOptions_1.OPTION_NAMESPACES) {
+        const bag = (0, xenonOptions_1.isOptionsObject)(caps) ? caps[namespace] : undefined;
+        if (bag !== undefined && bag !== null && !(0, xenonOptions_1.isOptionsObject)(bag)) {
+            return {
+                tiers: [...exports.LOCAL_HEALING_TIERS],
+                unreadable: `${namespace} is ${JSON.stringify(bag)}, not an object`,
+            };
+        }
+    }
+    const raw = (0, xenonOptions_1.xenonOptionsIn)(caps).healingTiers;
+    const tiers = coerceHealingTiersCap(raw);
+    return tiers === undefined || isHealingTierList(raw)
+        ? { tiers }
+        : {
+            tiers,
+            unreadable: `healingTiers is ${JSON.stringify(raw)}, not a list of tier numbers from 1 to 5`,
+        };
 }
 let HealingOrchestrator = class HealingOrchestrator {
     constructor(etalonService) {
@@ -120,7 +112,15 @@ let HealingOrchestrator = class HealingOrchestrator {
     }
     attemptHealing(sessionId, driver, strategy, selector, allowedTiers) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a, _b, _c;
+            // §2.7: when the session's xe:options.healingTiers capability is set,
+            // restrict dispatch to the allowed tier indices; absent -> unchanged.
+            const activeProviders = filterProvidersByTier(this.providers, allowedTiers);
+            if (activeProviders.length === 0) {
+                // Nothing to run, so nothing is collected either: no screenshot taken.
+                this.logger.info(`Session ${sessionId} allows no self-healing tier; ${strategy}=${selector} is not healed.`);
+                return null;
+            }
             this.logger.info(`🚨 Self-Healing triggered for session ${sessionId}. Broken locator: ${strategy}=${selector}`);
             // Span wraps the whole attempt. Original selector text is intentionally
             // kept off the span — high cardinality (long XPath strings) would explode
@@ -151,9 +151,6 @@ let HealingOrchestrator = class HealingOrchestrator {
                 return null;
             }
             // Tiered Execution: Try providers in order of cost/complexity.
-            // §2.7: when the session's xe:options.healingTiers capability is set,
-            // restrict dispatch to the allowed tier indices; absent -> unchanged.
-            const activeProviders = filterProvidersByTier(this.providers, allowedTiers);
             for (const provider of activeProviders) {
                 const tierStart = Date.now();
                 span.addEvent('tier_started', { tier: provider.name });
@@ -203,23 +200,11 @@ let HealingOrchestrator = class HealingOrchestrator {
                         else if (result.confidence > 0.7 && result.node) {
                             try {
                                 this.logger.info(`🧠 Learning from healing success: updating etalon for ${selector}`);
-                                // Recalculate path for ResilioTree if node is available
-                                let learnedPath = null;
-                                if (result.node) {
-                                    try {
-                                        const { Path } = yield Promise.resolve().then(() => __importStar(require('resiliotree')));
-                                        const pathNodes = [];
-                                        let curr = result.node;
-                                        while (curr) {
-                                            pathNodes.unshift(curr);
-                                            curr = curr.parent || curr.parentNode;
-                                        }
-                                        learnedPath = new Path(pathNodes).toJSON();
-                                    }
-                                    catch (_c) {
-                                        // resiliotree import is best-effort; learnedPath stays null
-                                    }
-                                }
+                                // The healed element's path through the page source, for the
+                                // Resilio tier. Through 2.14 this built it from the healed node
+                                // with resiliotree, which an xmldom element (every node a tier
+                                // returns) can't be, so it was always null.
+                                const learnedPath = (0, resilioPath_1.resilioPathOf)(result.node, (_a = context.pageSource) !== null && _a !== void 0 ? _a : '');
                                 yield this.etalonService.saveSignature(strategy, selector, result.node, learnedPath);
                             }
                             catch (learnErr) {
@@ -235,7 +220,7 @@ let HealingOrchestrator = class HealingOrchestrator {
                         span.setAttributes({
                             [attributes_1.ATTR.HEALING_TIER]: provider.name,
                             [attributes_1.ATTR.HEALING_CONFIDENCE]: result.confidence,
-                            [attributes_1.ATTR.HEALING_RESULT_STRATEGY]: (_a = result.recommendedStrategy) !== null && _a !== void 0 ? _a : 'xpath',
+                            [attributes_1.ATTR.HEALING_RESULT_STRATEGY]: (_b = result.recommendedStrategy) !== null && _b !== void 0 ? _b : 'xpath',
                             [attributes_1.ATTR.HEALING_DURATION_MS]: Date.now() - attemptStart,
                         });
                         span.setStatus({ code: api_1.SpanStatusCode.OK });
@@ -253,7 +238,7 @@ let HealingOrchestrator = class HealingOrchestrator {
                 // tier can plausibly succeed (e.g. missing prerequisites that all
                 // share). Saves an expensive LLM round-trip when upstream context
                 // collection failed.
-                if ((_b = provider.shouldSkipRemaining) === null || _b === void 0 ? void 0 : _b.call(provider, context)) {
+                if ((_c = provider.shouldSkipRemaining) === null || _c === void 0 ? void 0 : _c.call(provider, context)) {
                     this.logger.warn(`Tier ${provider.tier} (${provider.name}) advised skipping remaining tiers for selector=${selector}`);
                     HealingMetrics_1.HEALING_METRICS.recordSkippedRemaining(provider.tier, provider.name);
                     span.addEvent('tier_skipped_remaining', { tier: provider.name });
@@ -273,8 +258,8 @@ let HealingOrchestrator = class HealingOrchestrator {
     }
     /**
      * The OCR and Visual AI tiers find the element in the screenshot, so their
-     * `rect` is in its pixels. The interceptor taps it, and asks iOS for the
-     * element there, in the driver's coordinates (points on iOS), so it is
+     * `rect` is in its pixels. The interceptor returns a virtual element there,
+     * which a click taps in the driver's coordinates (points on iOS), so it is
      * converted here. If that can't be worked out on iOS, a virtual element
      * (only a position) is no use and the tier counts as failed; a real element
      * the tier resolved keeps its id and loses only the rect.

package/lib/src/services/healing/OcrHealingProvider.js

@@ -14,8 +14,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OcrHealingProvider = void 0;
 const types_1 = require("./types");
-const tesseract_js_1 = __importDefault(require("tesseract.js"));
+const typedi_1 = require("typedi");
 const logger_1 = __importDefault(require("../../logger"));
+const OmniVisionService_1 = require("../omni-vision/OmniVisionService");
 class OcrHealingProvider {
     constructor() {
         this.name = 'OCR Text Provider';
@@ -41,71 +42,47 @@ class OcrHealingProvider {
                 if (!soughtText)
                     return null;
                 this.logger.info(`Attempting OCR search for text: "${soughtText}"`);
-                // Run OCR on the screenshot
-                const buffer = Buffer.from(context.screenshotBase64, 'base64');
-                const result = yield tesseract_js_1.default.recognize(buffer, 'eng');
-                const { words } = result.data;
-                // Look for the best word match
-                const bestWord = words
-                    ? words.find((w) => w.text.toLowerCase().includes(soughtText.toLowerCase()) ||
-                        soughtText.toLowerCase().includes(w.text.toLowerCase()))
-                    : null;
-                if (bestWord) {
-                    this.logger.info(`✅ OCR found text "${bestWord.text}" at ${JSON.stringify(bestWord.bbox)}`);
-                    // Convert bbox to center coordinates
-                    const x = Math.round((bestWord.bbox.x0 + bestWord.bbox.x1) / 2);
-                    const y = Math.round((bestWord.bbox.y0 + bestWord.bbox.y1) / 2);
-                    // Try to get the REAL element at these coordinates by tapping
-                    try {
-                        // Use W3C Actions to tap at the OCR-detected coordinates, then find the element at that position
-                        const element = yield context.driver
-                            .findElement('-ios predicate string', `label CONTAINS[c] "${bestWord.text.replace(/"/g, '\\"')}"`)
-                            .catch(() => null);
-                        if (element) {
-                            const elementId = element.ELEMENT || element['element-6066-11e4-a52e-4f735466cecf'];
-                            if (elementId) {
-                                this.logger.info('🎯 OCR resolved to real element via predicate search');
-                                return {
-                                    id: elementId,
-                                    tier: this.tier,
-                                    confidence: bestWord.confidence / 100,
-                                    originalSelector: context.selector,
-                                    originalStrategy: context.strategy,
-                                    recommendedSelector: `ocr:text="${bestWord.text}"`,
-                                    recommendedStrategy: 'xenon:visual',
-                                    message: `Found text "${bestWord.text}" via local OCR (${bestWord.confidence.toFixed(0)}% confidence)`,
-                                    rect: {
-                                        x: bestWord.bbox.x0,
-                                        y: bestWord.bbox.y0,
-                                        width: bestWord.bbox.x1 - bestWord.bbox.x0,
-                                        height: bestWord.bbox.y1 - bestWord.bbox.y0,
-                                    },
-                                };
-                            }
-                        }
-                    }
-                    catch (predErr) {
-                        this.logger.debug(`Predicate search failed: ${predErr.message}`);
+                // Read the screenshot as Omni-Vision's `-custom:ai-text` does: the text
+                // may cover several neighbouring words ("Sign in"), and a word that is
+                // only part of it ("Log" for "Login") is no match. The first match in
+                // reading order, as `findElement` with that locator returns.
+                const [match] = yield typedi_1.Container.get(OmniVisionService_1.OmniVisionService).findTextInScreenshot(context.screenshotBase64, soughtText);
+                if (!match)
+                    return null;
+                this.logger.info(`✅ OCR found text "${match.text}" at ${JSON.stringify({ x0: match.x0, y0: match.y0, x1: match.x1, y1: match.y1 })}`);
+                const found = {
+                    tier: this.tier,
+                    confidence: match.confidence / 100,
+                    originalSelector: context.selector,
+                    originalStrategy: context.strategy,
+                    recommendedSelector: `ocr:text="${match.text}"`,
+                    recommendedStrategy: 'xenon:visual',
+                    message: `Found text "${match.text}" via local OCR (${match.confidence.toFixed(0)}% confidence)`,
+                    text: match.text,
+                    rect: {
+                        x: match.x0,
+                        y: match.y0,
+                        width: match.x1 - match.x0,
+                        height: match.y1 - match.y0,
+                    },
+                };
+                // On an iPhone, the element whose label holds the text, when there is one.
+                try {
+                    const element = yield context.driver
+                        .findElement('-ios predicate string', `label CONTAINS[c] "${match.text.replace(/"/g, '\\"')}"`)
+                        .catch(() => null);
+                    const elementId = (element === null || element === void 0 ? void 0 : element.ELEMENT) || (element === null || element === void 0 ? void 0 : element['element-6066-11e4-a52e-4f735466cecf']);
+                    if (elementId) {
+                        this.logger.info('🎯 OCR resolved to real element via predicate search');
+                        return Object.assign({ id: elementId }, found);
                     }
-                    // Fallback: Return coordinate-based result with virtual ID
-                    // The CommandInterceptor handles rect-based results via coordinate tap
-                    return {
-                        id: `healed_ocr_${Date.now()}`,
-                        tier: this.tier,
-                        confidence: bestWord.confidence / 100,
-                        originalSelector: context.selector,
-                        originalStrategy: context.strategy,
-                        recommendedSelector: `ocr:text="${bestWord.text}"`,
-                        recommendedStrategy: 'xenon:visual',
-                        message: `Found text "${bestWord.text}" via local OCR (${bestWord.confidence.toFixed(0)}% confidence)`,
-                        rect: {
-                            x: bestWord.bbox.x0,
-                            y: bestWord.bbox.y0,
-                            width: bestWord.bbox.x1 - bestWord.bbox.x0,
-                            height: bestWord.bbox.y1 - bestWord.bbox.y0,
-                        },
-                    };
                 }
+                catch (predErr) {
+                    this.logger.debug(`Predicate search failed: ${predErr.message}`);
+                }
+                // Otherwise where the text is: the interceptor returns it as a virtual
+                // element, which a click taps.
+                return Object.assign({ id: `healed_ocr_${Date.now()}_${Math.random().toString(36).slice(2, 8)}` }, found);
             }
             catch (err) {
                 this.logger.error(`Error during OCR healing: ${err.message}`);

package/lib/src/services/healing/ResilioTreeHealingProvider.js

@@ -14,10 +14,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResilioTreeHealingProvider = void 0;
 const types_1 = require("./types");
-const { Path, PathFinder, JSDOMParser, LCSPathDistance, HeuristicNodeDistance, } = require('resiliotree');
 const typedi_1 = require("typedi");
 const logger_1 = __importDefault(require("../../logger"));
 const HealedLocatorGenerator_1 = require("./HealedLocatorGenerator");
+const resilioPath_1 = require("./resilioPath");
+/**
+ * Tier 0: the element at the end of the path most like the one the selector's
+ * element had when the selector last worked (resilioPath.ts). It answers only
+ * when it is sure, which is when the element kept its identity (Android's
+ * resource-id, iOS's name) and moved in the tree: a positional XPath that
+ * broke when the layout changed. Anything less is the next tier's to decide.
+ */
 class ResilioTreeHealingProvider {
     constructor(etalonService) {
         this.etalonService = etalonService;
@@ -34,44 +41,45 @@ class ResilioTreeHealingProvider {
             }
             try {
                 const signature = yield this.etalonService.getSignature(context.selector);
-                if (!signature || !signature.path) {
+                if (!(0, resilioPath_1.isResilioPath)(signature === null || signature === void 0 ? void 0 : signature.path)) {
                     this.logger.debug(`No ResilioTree path found for selector: ${context.selector}`);
                     return null;
                 }
                 this.logger.info(`Attempting robust ResilioTree recovery for: ${context.selector}`);
-                // 1. Parse current page source into ResilioTree model
-                const parser = new JSDOMParser();
-                const targetRoot = parser.parse(context.pageSource);
-                // 2. Revive the saved path from JSON
-                const savedPath = Path.fromJSON(signature.path);
-                // 3. Find the nearest node using ResilioTree's PathFinder
-                const pathDistance = new LCSPathDistance();
-                const nodeDistance = new HeuristicNodeDistance();
-                const pathFinder = new PathFinder(pathDistance, nodeDistance);
-                const nearestNode = pathFinder.findNearest(savedPath, targetRoot);
-                if (nearestNode) {
-                    const candidateLocators = this.generator.generate(nearestNode);
-                    const recommendedXpath = candidateLocators[0] || this.generateXpath(nearestNode);
-                    this.logger.info(`ResilioTree suggested recovery XPath: ${recommendedXpath}`);
+                const nearest = (0, resilioPath_1.nearestElement)(signature.path, context.pageSource);
+                if (!nearest) {
+                    this.logger.info(`ResilioTree found no element it is sure of for: ${context.selector}`);
+                    return null;
+                }
+                if ((0, resilioPath_1.contradictsSelector)(nearest.element, context.strategy, context.selector)) {
+                    this.logger.info(`ResilioTree's element doesn't have the text the selector states; leaving it to the next tier: ${context.selector}`);
+                    return null;
+                }
+                // The first of the element's locators the driver finds, among those
+                // that select that element alone in the page source.
+                const candidates = (0, resilioPath_1.locatorsSelectingOnly)(nearest.element, this.generator.generate(nearest.element));
+                for (const candidate of candidates) {
                     try {
-                        const healedElement = yield context.driver.findElement('xpath', recommendedXpath);
-                        if (healedElement) {
-                            return {
-                                id: healedElement.ELEMENT || healedElement['element-6066-11e4-a52e-4f735466cecf'],
-                                originalSelector: context.selector,
-                                originalStrategy: context.strategy,
-                                recommendedSelector: recommendedXpath,
-                                recommendedStrategy: 'xpath',
-                                candidateSelectors: candidateLocators,
-                                confidence: 0.9, // ResilioTree path matching is high confidence
-                                tier: this.tier,
-                                node: nearestNode,
-                                message: `Recovered via ResilioTree path matching. New XPath: ${recommendedXpath}`,
-                            };
-                        }
+                        const found = yield context.driver.findElement('xpath', candidate);
+                        const id = (found === null || found === void 0 ? void 0 : found.ELEMENT) || (found === null || found === void 0 ? void 0 : found['element-6066-11e4-a52e-4f735466cecf']);
+                        if (!id)
+                            continue;
+                        this.logger.info(`ResilioTree recovered the element (score ${nearest.score.toFixed(2)}): ${candidate}`);
+                        return {
+                            id,
+                            originalSelector: context.selector,
+                            originalStrategy: context.strategy,
+                            recommendedSelector: candidate,
+                            recommendedStrategy: 'xpath',
+                            candidateSelectors: candidates,
+                            confidence: nearest.score,
+                            tier: this.tier,
+                            node: nearest.element,
+                            message: `Recovered via ResilioTree path matching. New XPath: ${candidate}`,
+                        };
                     }
-                    catch (e) {
-                        this.logger.debug(`Driver failed to find element suggested by ResilioTree: ${recommendedXpath}`);
+                    catch (_a) {
+                        this.logger.debug(`Driver failed to find element suggested by ResilioTree: ${candidate}`);
                     }
                 }
             }
@@ -81,22 +89,5 @@ class ResilioTreeHealingProvider {
             return null;
         });
     }
-    /**
-     * Generates an absolute XPath for a ResilioTree Node
-     */
-    generateXpath(node) {
-        const parts = [];
-        let curr = node;
-        while (curr) {
-            const tag = curr.tag.toLowerCase();
-            // Skip JSDOM added wrapper tags for mobile compatibility
-            if (tag !== 'html' && tag !== 'body') {
-                const index = curr.index + 1; // XPath is 1-based
-                parts.unshift(`${curr.tag}[${index}]`);
-            }
-            curr = curr.parent;
-        }
-        return `/${parts.join('/')}`;
-    }
 }
 exports.ResilioTreeHealingProvider = ResilioTreeHealingProvider;

package/lib/src/services/healing/VisualAiHealingProvider.js

@@ -42,7 +42,7 @@ class VisualAiHealingProvider {
                 if (coordinates && typeof coordinates.x === 'number' && typeof coordinates.y === 'number') {
                     this.logger.info(`✅ Visual AI found element at (${coordinates.x}, ${coordinates.y})`);
                     return {
-                        id: `healed_visual_${Date.now()}`,
+                        id: `healed_visual_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
                         tier: this.tier,
                         confidence: 0.8, // Basic vision models don't always give confidence, assuming high if found
                         originalSelector: context.selector,

package/lib/src/services/healing/fingerprintIdentity.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * What a stored fingerprint (`LocatorSignature.attributes`) says about which
+ * element it is, as opposed to where the element was (x, y, width, height).
+ *
+ * Through 2.14 every learnt fingerprint held only the rect and the type: the
+ * attribute reads failed (CommandInterceptor.triggerLearning). Fuzzy XML, which
+ * weighs position above everything else, then healed a selector to whatever
+ * element of that type sat at that spot. A fingerprint with no identity isn't
+ * used for position, and is learnt again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FINGERPRINT_IDENTITY_ATTRIBUTES = void 0;
+exports.meaningful = meaningful;
+exports.hasIdentity = hasIdentity;
+exports.attributesToLearn = attributesToLearn;
+exports.resourceIdName = resourceIdName;
+exports.stableIdentifierOf = stableIdentifierOf;
+exports.sameIdentifier = sameIdentifier;
+exports.sameText = sameText;
+/**
+ * The attributes that say which element a fingerprint is. Not `value`: on a
+ * text field it is what the test typed, which fingerprints no longer keep.
+ */
+exports.FINGERPRINT_IDENTITY_ATTRIBUTES = [
+    'resource-id',
+    'content-desc',
+    'accessibility-id',
+    'text',
+    'name',
+    'label',
+    'id',
+    'hint',
+];
+/**
+ * A value that says something: a string with more than spaces in it, and not
+ * "null", which is what UiAutomator2 answers for an attribute the element
+ * hasn't set (its getAttribute is String(value)).
+ */
+function meaningful(value) {
+    return typeof value === 'string' && value.trim() !== '' && value.trim() !== 'null';
+}
+/** Whether a fingerprint says anything about which element it is. */
+function hasIdentity(attributes) {
+    return exports.FINGERPRINT_IDENTITY_ATTRIBUTES.some((name) => meaningful(attributes === null || attributes === void 0 ? void 0 : attributes[name]));
+}
+/**
+ * The attributes learning asks a driver for: those it has. UiAutomator2
+ * throws for `id` and `label`, and its `name` is the text again; WebDriverAgent
+ * throws for anything but its own, so five of the old list were five failed
+ * round trips per selector learnt.
+ */
+function attributesToLearn(platformName) {
+    const platform = String(platformName !== null && platformName !== void 0 ? platformName : '').toLowerCase();
+    if (platform === 'android')
+        return ['resource-id', 'content-desc', 'text', 'hint'];
+    if (platform === 'ios' || platform === 'tvos')
+        return ['name', 'label'];
+    return ['resource-id', 'content-desc', 'text', 'hint', 'name', 'label'];
+}
+/**
+ * An Android resource-id without its package: `com.shop:id/pay` is `pay`.
+ * Fuzzy XML's veto asks whether two ids are the same this way: ids of one
+ * app share the package, and of a debug build another one. Its score still
+ * compares whole ids, where the shared package earns a share of the weight.
+ */
+function resourceIdName(resourceId) {
+    const at = resourceId.lastIndexOf(':id/');
+    if (at >= 0)
+        return resourceId.slice(at + 4);
+    return resourceId.slice(resourceId.lastIndexOf('/') + 1);
+}
+/**
+ * The identifier a developer gave the element, which stays when its text
+ * changes: an Android resource-id, or an iOS accessibility identifier (`name`
+ * when it isn't just the label; an element without one has its label as name).
+ */
+function stableIdentifierOf(attributes) {
+    const resourceId = attributes === null || attributes === void 0 ? void 0 : attributes['resource-id'];
+    if (meaningful(resourceId))
+        return { attribute: 'resource-id', value: resourceId };
+    const name = attributes === null || attributes === void 0 ? void 0 : attributes.name;
+    if (meaningful(name) && name !== (attributes === null || attributes === void 0 ? void 0 : attributes.label))
+        return { attribute: 'name', value: name };
+    return null;
+}
+// Built at run time: the compiler's target predates Unicode property escapes
+// in regular expression literals. Letters, their combining marks and digits,
+// in any script.
+const NOT_A_WORD = new RegExp('[^\\p{L}\\p{M}\\p{N}]+', 'gu');
+const CAMEL_TURN = new RegExp('([\\p{Ll}\\p{N}])(\\p{Lu})', 'gu');
+/** An identifier's words: split where camelCase turns and at anything but a letter or digit. */
+function identifierWords(identifier) {
+    return identifier
+        .normalize('NFC')
+        .replace(CAMEL_TURN, '$1 $2')
+        .toLowerCase()
+        .split(NOT_A_WORD)
+        .filter(Boolean);
+}
+/**
+ * Whether two identifiers name the same element: they have the same words,
+ * however written (btn-pay, pay_btn, payBtn). Any other pair names another
+ * element, and the text decides: an id that gains words is as often another
+ * element (pay_later, undo_delete) as a rename (checkout_pay), and letters
+ * alone can't tell follow from unfollow, or checkout.cancel from
+ * checkout.pay (64% of their letter pairs are shared). Two with no letter or
+ * digit between them can't be told apart, and count as the same.
+ */
+function sameIdentifier(a, b) {
+    const [wordsA, wordsB] = [new Set(identifierWords(a)), new Set(identifierWords(b))];
+    if (wordsA.size !== wordsB.size)
+        return false;
+    return [...wordsA].every((w) => wordsB.has(w));
+}
+/**
+ * Whether two texts read the same: case, punctuation and spacing aside, with
+ * accents composed (NFC). Combining marks count: Hindi दें and दो differ only
+ * by theirs. Nothing looser: "Log in" and "Log out", "Enable" and "Disable"
+ * are as alike by their letters as a reworded label is.
+ */
+function sameText(a, b) {
+    const read = (t) => t.normalize('NFC').toLowerCase().replace(NOT_A_WORD, ' ').trim();
+    const [textA, textB] = [read(a), read(b)];
+    return textA !== '' && textA === textB;
+}