feat(driver): candidate-ranking extension seam for the wildcard resolver

__kjs.setResolveRanker(fn) registers a ranker consulted by __kjs.resolve:
it receives the full matched-candidate list (same predicate as the default
path — visible, leaf-text match, DOM order) plus the resolve context, and
returns the ranked list; index selection then applies to that list. The
ranker may reorder matches or add candidates the default visible-only
filter excluded (e.g. a hidden element the caller knows how to reveal).

Behavior-compatible by default: with no ranker registered the resolver
keeps its exact short-circuit path; an identity ranker reproduces default
behavior; a throwing or non-array-returning ranker is ignored for that
resolution and logged.

Motivation: a downstream runtime that knows an open menu item should beat
an ambient same-text label (a text tie where DOM order shifts between
record and replay) previously had to monkeypatch __kjs.resolve wholesale.
The seam replaces that with a registered ranker the resolver owns, and is
the extension point richer candidate ranking (hidden-with-reveal-plan,
actionable-over-ambient, self-healing) can plug into without ever
clobbering the resolver.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ptrthomas

karate-core/src/main/resources/io/karatelabs/driver/driver.js

@@ -307,13 +307,36 @@
     // ==================== Wildcard Resolver ====================
     // Public API: __kjs.resolve(tag, text, index, contains)
 
+    /**
+     * Extension seam: register a candidate ranker consulted by resolve().
+     *
+     * The ranker receives (matches, ctx) where matches is the full list of
+     * elements satisfying the resolve criteria in DOM order (visible,
+     * leaf-text match \u2014 the same predicate the default path applies) and
+     * ctx is {tag, text, index, contains, selector} with text normalized.
+     * It returns the ranked candidate list; index selection then applies to
+     * that list. The ranker may reorder matches or add candidates of its own
+     * (e.g. elements the default visibility filter excluded). A ranker that
+     * throws or returns a non-array is ignored for that resolution.
+     *
+     * With no ranker registered, resolution behavior is unchanged (first
+     * visible leaf match in DOM order, short-circuit preserved).
+     * Pass null to unregister.
+     */
+    kjs.setResolveRanker = function(fn) {
+        this._resolveRanker = (typeof fn === 'function') ? fn : null;
+    };
+
     /**
      * Match candidates against text criteria.
      * Shared logic for light DOM and shadow DOM resolution.
      */
     kjs._resolveFromCandidates = function(candidates, tag, text, index, contains) {
         var selector = this.getSelector(tag);
         text = text.replace(/\s+/g, ' ').trim(); // normalize whitespace (including \u00a0)
+        if (this._resolveRanker) {
+            return this._resolveRanked(candidates, tag, text, index, contains, selector);
+        }
         var count = 0;
         for (var i = 0; i < candidates.length; i++) {
             var el = candidates[i];
@@ -337,6 +360,46 @@
         return null;
     };
 
+    /**
+     * Ranked resolution path (active only when a ranker is registered).
+     * Collects ALL matches with the same predicate the default path applies,
+     * hands them to the ranker, then applies the same index selection to the
+     * ranked list \u2014 so an identity ranker reproduces default behavior exactly.
+     */
+    kjs._resolveRanked = function(candidates, tag, text, index, contains, selector) {
+        var matches = [];
+        for (var i = 0; i < candidates.length; i++) {
+            var el = candidates[i];
+            if (!this.isVisible(el)) continue;
+            if (text === '') {
+                matches.push(el);
+                continue;
+            }
+            var elText = this.getVisibleText(el);
+            if (!elText) continue;
+            var ok = contains
+                ? elText.indexOf(text) !== -1
+                : elText === text;
+            if (ok && !this.hasMatchingDescendant(el, text, contains, selector)) {
+                matches.push(el);
+            }
+        }
+        var ranked = matches;
+        try {
+            var result = this._resolveRanker(matches.slice(), {
+                tag: tag, text: text, index: index, contains: contains, selector: selector
+            });
+            if (Array.isArray(result)) ranked = result;
+        } catch (e) {
+            this.log('resolve ranker failed, using default order', {error: '' + e});
+        }
+        // same selection semantics as the default path: the index-th match, 1-based
+        for (var j = 0; j < ranked.length; j++) {
+            if (j + 1 === index) return ranked[j];
+        }
+        return null;
+    };
+
     kjs.resolve = function(tag, text, index, contains) {
         var selector = this.getSelector(tag);
         // Try light DOM first

karate-core/src/test/java/io/karatelabs/driver/e2e/LocatorsE2eTest.java

@@ -495,4 +495,76 @@ void testActionJsOnMissingElementFailsLoudlyNamingLocator() {
         }
     }
 
+    // ========== Resolve ranker (the __kjs.setResolveRanker extension seam) ==========
+    // A downstream runtime (e.g. an agent layer that knows an open menu item should
+    // beat an ambient same-text label) can register a candidate ranker instead of
+    // monkeypatching __kjs.resolve. The seam's contract: with no ranker — or a
+    // broken one — resolution is EXACTLY the default (first visible leaf match in
+    // DOM order); a registered ranker reorders or augments the matched candidate
+    // list, and index selection applies to the ranked list.
+
+    @Test
+    void testResolveRankerReordersTieAndUnregisters() {
+        driver.setUrl("data:text/html," +
+                "<div id='ambient'>Ray</div>" +
+                "<div id='menu-item'>Ray</div>");
+        // default: first visible match in DOM order
+        assertEquals("ambient", driver.attribute("{div}Ray", "id"));
+        driver.script("window.__kjs.setResolveRanker(function(matches, ctx){"
+                + " return matches.slice().reverse(); })");
+        assertEquals("menu-item", driver.attribute("{div}Ray", "id"));
+        // unregister restores the default order
+        driver.script("window.__kjs.setResolveRanker(null)");
+        assertEquals("ambient", driver.attribute("{div}Ray", "id"));
+    }
+
+    @Test
+    void testResolveRankerIndexAppliesToRankedList() {
+        driver.setUrl("data:text/html," +
+                "<b id='one'>X</b><b id='two'>X</b><b id='three'>X</b>");
+        // rotate: [two, three, one]
+        driver.script("window.__kjs.setResolveRanker(function(m){ m.push(m.shift()); return m; })");
+        assertEquals("two", driver.attribute("{b:1}X", "id"));
+        assertEquals("three", driver.attribute("{b:2}X", "id"));
+        assertEquals("one", driver.attribute("{b:3}X", "id"));
+        // index beyond the ranked list still misses
+        assertFalse(driver.exists("{b:4}X"));
+    }
+
+    @Test
+    void testResolveRankerIdentityKeepsDefaultBehavior() {
+        driver.script("window.__kjs.setResolveRanker(function(m){ return m; })");
+        assertEquals("1", driver.attribute("{li:1}Item", "data-index"));
+        assertEquals("2", driver.attribute("{li:2}Item", "data-index"));
+        assertEquals("3", driver.attribute("{li:3}Item", "data-index"));
+        assertEquals("Click Me", driver.text("{button}Click Me"));
+        assertFalse(driver.exists("{button}NonExistentText"));
+    }
+
+    @Test
+    void testResolveRankerFailuresFallBackToDefaultOrder() {
+        driver.setUrl("data:text/html," +
+                "<div id='first'>Twin</div>" +
+                "<div id='second'>Twin</div>");
+        // a throwing ranker must not break resolution
+        driver.script("window.__kjs.setResolveRanker(function(){ throw new Error('boom'); })");
+        assertEquals("first", driver.attribute("{div}Twin", "id"));
+        // a non-array return is ignored
+        driver.script("window.__kjs.setResolveRanker(function(){ return 'nope'; })");
+        assertEquals("first", driver.attribute("{div}Twin", "id"));
+    }
+
+    @Test
+    void testResolveRankerMayAddCandidatesTheDefaultFilterExcluded() {
+        // the ranker may inject candidates of its own — e.g. a hidden element it
+        // knows how to reveal — which the default visible-only filter never emits
+        driver.setUrl("data:text/html," +
+                "<div id='visible-twin'>Save</div>" +
+                "<div id='hidden-menu' style='display:none'>Save</div>");
+        assertEquals("visible-twin", driver.attribute("{div}Save", "id"));
+        driver.script("window.__kjs.setResolveRanker(function(m){"
+                + " m.unshift(document.getElementById('hidden-menu')); return m; })");
+        assertEquals("hidden-menu", driver.attribute("{div}Save", "id"));
+    }
+
 }