@hypothesi/tauri-mcp-server 0.8.1 → 0.8.3

package/dist/driver/plugin-client.js

@@ -127,43 +127,58 @@ export class PluginClient extends EventEmitter {
         }
     }
     /**
-     * Send a command to the plugin and wait for response
+     * Send a command to the plugin and wait for response.
+     *
+     * Automatically retries on transient "not found" errors (e.g. window not
+     * yet registered after WebSocket connect) with exponential backoff.
      */
     async sendCommand(command, timeoutMs = 5000) {
-        // If not connected, try to reconnect first
-        if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
-            try {
-                await this.connect();
+        const maxRetries = 3;
+        const baseDelayMs = 100;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            // If not connected, try to reconnect first
+            if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+                try {
+                    await this.connect();
+                }
+                catch {
+                    throw new Error('Not connected to plugin and reconnection failed');
+                }
             }
-            catch {
-                throw new Error('Not connected to plugin and reconnection failed');
+            // Double-check connection after reconnect attempt
+            if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+                throw new Error('Not connected to plugin');
             }
-        }
-        // Double-check connection after reconnect attempt
-        if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
-            throw new Error('Not connected to plugin');
-        }
-        // Generate unique ID for this request
-        const id = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-        const commandWithId = { ...command, id };
-        return new Promise((resolve, reject) => {
-            // Set up timeout
-            const timeout = setTimeout(() => {
-                this._pendingRequests.delete(id);
-                reject(new Error(`Request timeout after ${timeoutMs}ms`));
-            }, timeoutMs);
-            // Store pending request
-            this._pendingRequests.set(id, { resolve, reject, timeout });
-            // Send command
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            this._ws.send(JSON.stringify(commandWithId), (error) => {
-                if (error) {
-                    clearTimeout(timeout);
+            // Generate unique ID for this request
+            const id = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            const commandWithId = { ...command, id };
+            const response = await new Promise((resolve, reject) => {
+                // Set up timeout
+                const timeout = setTimeout(() => {
                     this._pendingRequests.delete(id);
-                    reject(error);
-                }
+                    reject(new Error(`Request timeout after ${timeoutMs}ms`));
+                }, timeoutMs);
+                // Store pending request
+                this._pendingRequests.set(id, { resolve, reject, timeout });
+                // Send command
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                this._ws.send(JSON.stringify(commandWithId), (error) => {
+                    if (error) {
+                        clearTimeout(timeout);
+                        this._pendingRequests.delete(id);
+                        reject(error);
+                    }
+                });
             });
-        });
+            // Retry on "not found" errors (window not yet registered)
+            if (!response.success && response.error?.includes('not found') && attempt < maxRetries) {
+                await new Promise((r) => { setTimeout(r, baseDelayMs * Math.pow(2, attempt)); });
+                continue;
+            }
+            return response;
+        }
+        // Unreachable — loop always returns or throws — but satisfies TypeScript
+        throw new Error('Retry attempts exhausted');
     }
     /**
      * Check if connected

package/dist/driver/scripts/dom-snapshot.js

@@ -18,12 +18,13 @@
  *
  * @param {Object} params
  * @param {string} params.type - Snapshot type ('accessibility' or 'structure')
- * @param {string|null} params.selector - Optional CSS selector to scope snapshot
+ * @param {string|null} params.selector - Optional selector to scope snapshot (CSS, XPath, text, or ref ID)
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
  */
 (function(params) {
    'use strict';
 
-   const { type, selector } = params;
+   const { type, selector, strategy } = params;
 
    // ARIA states to include in snapshot (used by accessibility type)
    const ARIA_STATES = [
@@ -56,8 +57,9 @@
       return refMap.get(element);
    }
 
-   window.__MCP_ARIA_REFS__ = refMap;
-   window.__MCP_ARIA_REFS_REVERSE__ = reverseRefMap;
+   window.__MCP__ = window.__MCP__ || {};
+   window.__MCP__.refs = refMap;
+   window.__MCP__.reverseRefs = reverseRefMap;
 
    // ========================================================================
    // Visibility (using aria-api for correct aria-hidden inheritance)
@@ -444,18 +446,17 @@
 
       if (selector) {
          try {
-            document.querySelector(selector);
+            var structureElements = window.__MCP__.resolveAll(selector, strategy);
          } catch (e) {
-            return 'Error: Invalid CSS selector "' + selector + '": ' + e.message;
+            return 'Error: Invalid selector "' + selector + '" (strategy: ' + strategy + '): ' + e.message;
          }
 
-         var structureElements = document.querySelectorAll(selector);
          if (structureElements.length === 0) {
-            return 'Error: No elements found matching selector "' + selector + '"';
+            return 'Error: No elements found matching selector "' + selector + '" (strategy: ' + strategy + ')';
          }
 
-         structureRoots = Array.from(structureElements);
-         structureScopeInfo = '# Scoped to: ' + selector + '\n';
+         structureRoots = structureElements;
+         structureScopeInfo = '# Scoped to: ' + selector + (strategy !== 'css' ? ' (strategy: ' + strategy + ')' : '') + '\n';
          if (structureRoots.length > 1) structureScopeInfo += '# ' + structureRoots.length + ' elements matched\n';
       } else {
          structureRoots = [document.body];
@@ -497,18 +498,17 @@
 
    if (selector) {
       try {
-         document.querySelector(selector);
+         var elements = window.__MCP__.resolveAll(selector, strategy);
       } catch (e) {
-         return 'Error: Invalid CSS selector "' + selector + '": ' + e.message;
+         return 'Error: Invalid selector "' + selector + '" (strategy: ' + strategy + '): ' + e.message;
       }
 
-      var elements = document.querySelectorAll(selector);
       if (elements.length === 0) {
-         return 'Error: No elements found matching selector "' + selector + '"';
+         return 'Error: No elements found matching selector "' + selector + '" (strategy: ' + strategy + ')';
       }
 
-      roots = Array.from(elements);
-      scopeInfo = '# Scoped to: ' + selector + '\n';
+      roots = elements;
+      scopeInfo = '# Scoped to: ' + selector + (strategy !== 'css' ? ' (strategy: ' + strategy + ')' : '') + '\n';
       if (roots.length > 1) scopeInfo += '# ' + roots.length + ' elements matched\n';
    } else {
       roots = [document.body];

package/dist/driver/scripts/find-element.js

@@ -7,41 +7,8 @@
  */
 (function(params) {
    const { selector, strategy } = params;
-   let element;
 
-   // Check if it's a ref ID first (works with any strategy)
-   const refMatch = selector.match(/^(?:ref=)?(e\d+)$/);
-   if (refMatch) {
-      const refId = refMatch[1],
-            refMap = window.__MCP_ARIA_REFS_REVERSE__;
-      if (refMap) {
-         element = refMap.get(refId);
-      }
-   } else if (strategy === 'text') {
-      // Find element containing text
-      const xpath = "//*[contains(text(), '" + selector + "')]";
-      const result = document.evaluate(
-         xpath,
-         document,
-         null,
-         XPathResult.FIRST_ORDERED_NODE_TYPE,
-         null
-      );
-      element = result.singleNodeValue;
-   } else if (strategy === 'xpath') {
-      // XPath selector
-      const result = document.evaluate(
-         selector,
-         document,
-         null,
-         XPathResult.FIRST_ORDERED_NODE_TYPE,
-         null
-      );
-      element = result.singleNodeValue;
-   } else {
-      // CSS selector (default)
-      element = document.querySelector(selector);
-   }
+   var element = window.__MCP__.resolveRef(selector, strategy);
 
    if (element) {
       const outerHTML = element.outerHTML;
@@ -49,7 +16,10 @@
       const truncated = outerHTML.length > 5000
          ? outerHTML.substring(0, 5000) + '...'
          : outerHTML;
-      return 'Found element: ' + truncated;
+      var msg = 'Found element: ' + truncated;
+      var count = window.__MCP__.countAll(selector, strategy);
+      if (count > 1) msg += '\n(+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+      return msg;
    }
 
    return 'Element not found';

package/dist/driver/scripts/focus.js

@@ -2,29 +2,23 @@
  * Focus an element
  *
  * @param {Object} params
- * @param {string} params.selector - CSS selector or ref ID (e.g., "ref=e3") for element to focus
+ * @param {string} params.selector - CSS selector, XPath, text, or ref ID (e.g., "ref=e3") for element to focus
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
  */
 (function(params) {
-   const { selector } = params;
+   const { selector, strategy } = params;
 
-   // Resolve element from CSS selector or ref ID (e.g., "ref=e3" or "e3")
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^(?:ref=)?(e\d+)$/);
-      if (refMatch) {
-         var refId = refMatch[1],
-             refMap = window.__MCP_ARIA_REFS_REVERSE__;
-         if (!refMap) throw new Error('Ref "' + refId + '" not found. Run webview_dom_snapshot first to index elements.');
-         var el = refMap.get(refId);
-         if (!el) throw new Error('Ref "' + refId + '" not found. The DOM may have changed since the snapshot.');
-         return el;
-      }
-      var el = document.querySelector(selectorOrRef);
+      var el = window.__MCP__.resolveRef(selectorOrRef, strategy);
       if (!el) throw new Error('Element not found: ' + selectorOrRef);
       return el;
    }
 
    const element = resolveElement(selector);
    element.focus();
-   return `Focused element: ${selector}`;
+   var msg = 'Focused element: ' + selector;
+   var count = window.__MCP__.countAll(selector, strategy);
+   if (count > 1) msg += ' (+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+   return msg;
 })

package/dist/driver/scripts/get-styles.js

@@ -2,46 +2,33 @@
  * Get computed CSS styles for elements
  *
  * @param {Object} params
- * @param {string} params.selector - CSS selector or ref ID (e.g., "ref=e3") for element(s)
+ * @param {string} params.selector - CSS selector, XPath, text, or ref ID (e.g., "ref=e3") for element(s)
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
  * @param {string[]} params.properties - Specific CSS properties to retrieve
  * @param {boolean} params.multiple - Whether to get styles for all matching elements
  */
 (function(params) {
-   const { selector, properties, multiple } = params;
+   const { selector, strategy, properties, multiple } = params;
 
-   // Resolve element from CSS selector or ref ID (e.g., "ref=e3" or "e3")
-   function resolveElement(selectorOrRef) {
-      if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^(?:ref=)?(e\d+)$/);
-      if (refMatch) {
-         var refId = refMatch[1],
-             refMap = window.__MCP_ARIA_REFS_REVERSE__;
-         if (!refMap) throw new Error('Ref "' + refId + '" not found. Run webview_dom_snapshot first to index elements.');
-         var el = refMap.get(refId);
-         if (!el) throw new Error('Ref "' + refId + '" not found. The DOM may have changed since the snapshot.');
-         return el;
-      }
-      var el = document.querySelector(selectorOrRef);
-      if (!el) throw new Error('Element not found: ' + selectorOrRef);
-      return el;
-   }
+   var elements;
 
-   // Check if selector is a ref ID - if so, multiple doesn't apply
-   const isRef = /^(?:ref=)?(e\d+)$/.test(selector);
-   const elements = isRef
-      ? [resolveElement(selector)]
-      : (multiple ? Array.from(document.querySelectorAll(selector)) : [document.querySelector(selector)]);
+   if (multiple) {
+      elements = window.__MCP__.resolveAll(selector, strategy);
+   } else {
+      var el = window.__MCP__.resolveRef(selector, strategy);
+      elements = el ? [el] : [];
+   }
 
    if (!elements[0]) {
-      throw new Error(`Element not found: ${selector}`);
+      throw new Error('Element not found: ' + selector);
    }
 
-   const results = elements.map(element => {
+   const results = elements.map(function(element) {
       const styles = window.getComputedStyle(element);
 
       if (properties.length > 0) {
          const result = {};
-         properties.forEach(prop => {
+         properties.forEach(function(prop) {
             result[prop] = styles.getPropertyValue(prop);
          });
          return result;

package/dist/driver/scripts/html2canvas-loader.js

@@ -22,7 +22,11 @@ export function getHtml2CanvasSource() {
         // Resolve the path to html2canvas-pro.js (UMD build)
         // Note: We use the main entry point since the minified version isn't exported
         const html2canvasProPath = require.resolve('html2canvas-pro');
-        html2canvasProSource = readFileSync(html2canvasProPath, 'utf-8');
+        html2canvasProSource = readFileSync(html2canvasProPath, 'utf-8')
+            // Strip sourceMappingURL to prevent the browser from trying to fetch the
+            // .map file relative to the page's base URL (which fails when the app is
+            // served under a sub-path like '/some/path/').
+            .replace(/\/\/[#@]\s*sourceMappingURL=.*/g, '');
     }
     return html2canvasProSource;
 }

package/dist/driver/scripts/index.js

@@ -13,6 +13,7 @@ function loadScript(name) {
 }
 // Load scripts once at module initialization
 export const SCRIPTS = {
+    resolveRef: loadScript('resolve-ref'),
     interact: loadScript('interact'),
     swipe: loadScript('swipe'),
     keyboard: loadScript('keyboard'),
@@ -22,6 +23,14 @@ export const SCRIPTS = {
     findElement: loadScript('find-element'),
     domSnapshot: loadScript('dom-snapshot'),
 };
+/** Script ID used for resolve-ref in the script registry. */
+export const RESOLVE_REF_SCRIPT_ID = '__mcp_resolve_ref__';
+/**
+ * Get the resolve-ref script source code.
+ */
+export function getResolveRefSource() {
+    return SCRIPTS.resolveRef;
+}
 /**
  * Build a script invocation with parameters
  * The script should be an IIFE that accepts a params object
@@ -32,24 +41,28 @@ export function buildScript(script, params) {
 /**
  * Build a script for typing text (uses the keyboard script's typeText function)
  */
-export function buildTypeScript(selector, text) {
+export function buildTypeScript(selector, text, strategy) {
     const escapedText = text.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    const escapedSelector = selector.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    const strat = strategy || 'css';
     return `
       (function() {
-         const selector = '${selector}';
+         const selector = '${escapedSelector}';
+         const strategy = '${strat}';
          const text = '${escapedText}';
 
-         const element = document.querySelector(selector);
-         if (!element) {
-            throw new Error('Element not found: ' + selector);
-         }
+         var element = window.__MCP__.resolveRef(selector, strategy);
+         if (!element) throw new Error('Element not found: ' + selector);
 
          element.focus();
          element.value = text;
          element.dispatchEvent(new Event('input', { bubbles: true }));
          element.dispatchEvent(new Event('change', { bubbles: true }));
 
-         return 'Typed "' + text + '" into ' + selector;
+         var msg = 'Typed "' + text + '" into ' + selector;
+         var count = window.__MCP__.countAll(selector, strategy);
+         if (count > 1) msg += ' (+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+         return msg;
       })()
    `;
 }

package/dist/driver/scripts/interact.js

@@ -4,7 +4,8 @@
  *
  * @param {Object} params
  * @param {string} params.action - The action to perform
- * @param {string|null} params.selector - CSS selector or ref ID (e.g., "ref=e3") for the element
+ * @param {string|null} params.selector - CSS selector, XPath, text, or ref ID (e.g., "ref=e3") for the element
+ * @param {string} params.strategy - Selector strategy: 'css', 'xpath', or 'text'
  * @param {number|null} params.x - X coordinate
  * @param {number|null} params.y - Y coordinate
  * @param {number} params.duration - Duration for long-press
@@ -12,25 +13,22 @@
  * @param {number} params.scrollY - Vertical scroll amount
  */
 (function(params) {
-   const { action, selector, x, y, duration, scrollX, scrollY } = params;
+   const { action, selector, strategy, x, y, duration, scrollX, scrollY } = params;
 
-   // Resolve element from CSS selector or ref ID (e.g., "ref=e3" or "e3")
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^(?:ref=)?(e\d+)$/);
-      if (refMatch) {
-         var refId = refMatch[1],
-             refMap = window.__MCP_ARIA_REFS_REVERSE__;
-         if (!refMap) throw new Error('Ref "' + refId + '" not found. Run webview_dom_snapshot first to index elements.');
-         var el = refMap.get(refId);
-         if (!el) throw new Error('Ref "' + refId + '" not found. The DOM may have changed since the snapshot.');
-         return el;
-      }
-      var el = document.querySelector(selectorOrRef);
+      var el = window.__MCP__.resolveRef(selectorOrRef, strategy);
       if (!el) throw new Error('Element not found: ' + selectorOrRef);
       return el;
    }
 
+   function matchHint() {
+      if (!selector) return '';
+      var count = window.__MCP__.countAll(selector, strategy);
+      if (count > 1) return ' (+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+      return '';
+   }
+
    let element = null;
    let targetX, targetY;
 
@@ -70,7 +68,7 @@
          element.dispatchEvent(new MouseEvent('mouseup', eventOptions));
          element.dispatchEvent(new MouseEvent('click', eventOptions));
       }
-      return `Clicked at (${targetX}, ${targetY})`;
+      return `Clicked at (${targetX}, ${targetY})` + matchHint();
    }
 
    if (action === 'double-click') {
@@ -83,7 +81,7 @@
          element.dispatchEvent(new MouseEvent('click', eventOptions));
          element.dispatchEvent(new MouseEvent('dblclick', eventOptions));
       }
-      return `Double-clicked at (${targetX}, ${targetY})`;
+      return `Double-clicked at (${targetX}, ${targetY})` + matchHint();
    }
 
    if (action === 'long-press') {
@@ -93,7 +91,7 @@
             element.dispatchEvent(new MouseEvent('mouseup', eventOptions));
          }, duration);
       }
-      return `Long-pressed at (${targetX}, ${targetY}) for ${duration}ms`;
+      return `Long-pressed at (${targetX}, ${targetY}) for ${duration}ms` + matchHint();
    }
 
    if (action === 'scroll') {
@@ -105,7 +103,7 @@
             scrollTarget.scrollLeft += scrollX;
             scrollTarget.scrollTop += scrollY;
          }
-         return `Scrolled by (${scrollX}, ${scrollY}) pixels`;
+         return `Scrolled by (${scrollX}, ${scrollY}) pixels` + matchHint();
       }
       return 'No scroll performed (scrollX and scrollY are both 0)';
    }

package/dist/driver/scripts/resolve-ref.js

@@ -0,0 +1,112 @@
+/**
+ * Shared ref resolver - always available via window.__MCP__.resolveRef.
+ * Accepts a ref ID ("e3", "ref=e3", "[ref=e3]"), CSS selector, XPath, or text.
+ * Returns the DOM element, or null if not found.
+ *
+ * Reads window.__MCP__.reverseRefs dynamically at call time so it always
+ * uses the latest snapshot's data.
+ *
+ * Also provides:
+ * - resolveAll(selector, strategy) - returns an Array of matching elements
+ * - countAll(selector, strategy)   - returns the total match count
+ */
+(function() {
+   window.__MCP__ = window.__MCP__ || {};
+
+   var REF_PATTERN = /^\[?(?:ref=)?(e\d+)\]?$/;
+
+   function xpathForText(text) {
+      // Escape single quotes for XPath by splitting on ' and using concat()
+      if (text.indexOf("'") === -1) {
+         return "//*[contains(text(), '" + text + "')]";
+      }
+      var parts = text.split("'");
+      var expr = 'concat(' + parts.map(function(p, i) {
+         return (i > 0 ? ",\"'\",": '') + "'" + p + "'";
+      }).join('') + ')';
+      return '//*[contains(text(), ' + expr + ')]';
+   }
+
+   /**
+    * Resolve a single element by selector and strategy.
+    * @param {string} selectorOrRef - Selector, ref ID, XPath, or text
+    * @param {string} [strategy]    - 'css' (default), 'xpath', or 'text'
+    * @returns {Element|null}
+    */
+   window.__MCP__.resolveRef = function(selectorOrRef, strategy) {
+      if (!selectorOrRef) return null;
+
+      // Ref IDs always take priority regardless of strategy
+      var refMatch = selectorOrRef.match(REF_PATTERN);
+      if (refMatch) {
+         var reverseRefs = window.__MCP__.reverseRefs;
+         if (!reverseRefs) {
+            throw new Error('Ref IDs require a snapshot. Run webview_dom_snapshot first to index elements.');
+         }
+         return reverseRefs.get(refMatch[1]) || null;
+      }
+
+      if (strategy === 'text') {
+         var xpath = xpathForText(selectorOrRef);
+         var result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+         return result.singleNodeValue;
+      }
+
+      if (strategy === 'xpath') {
+         var result = document.evaluate(selectorOrRef, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+         return result.singleNodeValue;
+      }
+
+      // Default: CSS selector
+      return document.querySelector(selectorOrRef);
+   };
+
+   /**
+    * Resolve all matching elements as an Array.
+    * @param {string} selector  - Selector, XPath, or text
+    * @param {string} [strategy] - 'css' (default), 'xpath', or 'text'
+    * @returns {Element[]}
+    */
+   window.__MCP__.resolveAll = function(selector, strategy) {
+      if (!selector) return [];
+
+      // Ref IDs resolve to a single element
+      var refMatch = selector.match(REF_PATTERN);
+      if (refMatch) {
+         var el = window.__MCP__.resolveRef(selector);
+         return el ? [el] : [];
+      }
+
+      if (strategy === 'text') {
+         var xpath = xpathForText(selector);
+         var snapshot = document.evaluate(xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+         var results = [];
+         for (var i = 0; i < snapshot.snapshotLength; i++) {
+            results.push(snapshot.snapshotItem(i));
+         }
+         return results;
+      }
+
+      if (strategy === 'xpath') {
+         var snapshot = document.evaluate(selector, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+         var results = [];
+         for (var i = 0; i < snapshot.snapshotLength; i++) {
+            results.push(snapshot.snapshotItem(i));
+         }
+         return results;
+      }
+
+      // Default: CSS
+      return Array.from(document.querySelectorAll(selector));
+   };
+
+   /**
+    * Count all matching elements.
+    * @param {string} selector  - Selector, XPath, or text
+    * @param {string} [strategy] - 'css' (default), 'xpath', or 'text'
+    * @returns {number}
+    */
+   window.__MCP__.countAll = function(selector, strategy) {
+      return window.__MCP__.resolveAll(selector, strategy).length;
+   };
+})();

package/dist/driver/scripts/wait-for.js

@@ -4,42 +4,38 @@
  * @param {Object} params
  * @param {string} params.type - What to wait for: 'selector', 'text', 'ipc-event'
  * @param {string} params.value - Selector/ref ID, text, or event name to wait for
+ * @param {string} params.strategy - Selector strategy (applies when type is 'selector'): 'css', 'xpath', or 'text'
  * @param {number} params.timeout - Timeout in milliseconds
  */
 (async function(params) {
-   const { type, value, timeout } = params;
+   const { type, value, strategy, timeout } = params;
    const startTime = Date.now();
 
-   // Resolve element from CSS selector or ref ID (e.g., "ref=e3" or "e3")
    function resolveElement(selectorOrRef) {
       if (!selectorOrRef) return null;
-      var refMatch = selectorOrRef.match(/^(?:ref=)?(e\d+)$/);
-      if (refMatch) {
-         var refId = refMatch[1],
-             refMap = window.__MCP_ARIA_REFS_REVERSE__;
-         if (!refMap) return null; // For wait-for, return null instead of throwing
-         return refMap.get(refId) || null;
-      }
-      return document.querySelector(selectorOrRef);
+      return window.__MCP__.resolveRef(selectorOrRef, strategy);
    }
 
-   return new Promise((resolve, reject) => {
+   return new Promise(function(resolve, reject) {
       function check() {
          if (Date.now() - startTime > timeout) {
-            reject(new Error(`Timeout waiting for ${type}: ${value}`));
+            reject(new Error('Timeout waiting for ' + type + ': ' + value));
             return;
          }
 
          if (type === 'selector') {
-            const element = resolveElement(value);
+            var element = resolveElement(value);
             if (element) {
-               resolve(`Element found: ${value}`);
+               var msg = 'Element found: ' + value;
+               var count = window.__MCP__.countAll(value, strategy);
+               if (count > 1) msg += ' (+' + (count - 1) + ' more match' + (count - 1 === 1 ? '' : 'es') + ')';
+               resolve(msg);
                return;
             }
          } else if (type === 'text') {
-            const found = document.body.innerText.includes(value);
+            var found = document.body.innerText.includes(value);
             if (found) {
-               resolve(`Text found: ${value}`);
+               resolve('Text found: ' + value);
                return;
             }
          } else if (type === 'ipc-event') {

package/dist/driver/webview-executor.js

@@ -4,6 +4,7 @@ import { hasActiveSession, getDefaultSession, resolveTargetApp } from './session
 import { createMcpLogger } from '../logger.js';
 import { buildScreenshotScript, buildScreenshotCaptureScript, getHtml2CanvasSource, HTML2CANVAS_SCRIPT_ID, } from './scripts/html2canvas-loader.js';
 import { registerScript, isScriptRegistered } from './script-manager.js';
+import { getResolveRefSource, RESOLVE_REF_SCRIPT_ID } from './scripts/index.js';
 /**
  * WebView Executor - Native IPC-based JavaScript execution
  *
@@ -44,6 +45,8 @@ export async function ensureReady() {
     if (session) {
         await connectPlugin(session.host, session.port);
     }
+    // Register the resolve-ref helper so ref-based selectors work in all tools
+    await registerScript(RESOLVE_REF_SCRIPT_ID, 'inline', getResolveRefSource());
     isInitialized = true;
 }
 /**

package/dist/driver/webview-interactions.js

@@ -15,12 +15,22 @@ export const WindowTargetSchema = z.object({
     appIdentifier: z.union([z.string(), z.number()]).optional().describe('App port or bundle ID to target. Defaults to the only connected app or the default app if multiple are connected.'),
 });
 // ============================================================================
+// Shared Selector Strategy
+// ============================================================================
+/**
+ * Reusable strategy field for tools that accept a selector.
+ * Defaults to 'css' for backward compatibility.
+ */
+const selectorStrategyField = z.enum(['css', 'xpath', 'text']).default('css').describe('Selector strategy: "css" (default) for CSS selectors, "xpath" for XPath expressions, ' +
+    '"text" to find elements containing the given text. Ref IDs (e.g., "ref=e3") work with any strategy.');
+// ============================================================================
 // Schemas
 // ============================================================================
 export const InteractSchema = WindowTargetSchema.extend({
     action: z.enum(['click', 'double-click', 'long-press', 'scroll', 'swipe', 'focus'])
         .describe('Type of interaction to perform'),
-    selector: z.string().optional().describe('CSS selector for the element to interact with'),
+    selector: z.string().optional().describe('Element selector: CSS selector (default), XPath expression, text content, or ref ID (e.g., "ref=e3")'),
+    strategy: selectorStrategyField,
     x: z.number().optional().describe('X coordinate for direct coordinate interaction'),
     y: z.number().optional().describe('Y coordinate for direct coordinate interaction'),
     duration: z.number().optional()
@@ -42,7 +52,9 @@ export const ScreenshotSchema = WindowTargetSchema.extend({
 export const KeyboardSchema = WindowTargetSchema.extend({
     action: z.enum(['type', 'press', 'down', 'up'])
         .describe('Keyboard action type: "type" for typing text into an element, "press/down/up" for key events'),
-    selector: z.string().optional().describe('CSS selector for element to type into (required for "type" action)'),
+    selector: z.string().optional().describe('Element selector for element to type into (required for "type" action): ' +
+        'CSS selector (default), XPath, text content, or ref ID'),
+    strategy: selectorStrategyField,
     text: z.string().optional().describe('Text to type (required for "type" action)'),
     key: z.string().optional().describe('Key to press (required for "press/down/up" actions, e.g., "Enter", "a", "Escape")'),
     modifiers: z.array(z.enum(['Control', 'Alt', 'Shift', 'Meta'])).optional().describe('Modifier keys to hold'),
@@ -50,10 +62,12 @@ export const KeyboardSchema = WindowTargetSchema.extend({
 export const WaitForSchema = WindowTargetSchema.extend({
     type: z.enum(['selector', 'text', 'ipc-event']).describe('What to wait for'),
     value: z.string().describe('Selector, text content, or IPC event name to wait for'),
+    strategy: selectorStrategyField.describe('Selector strategy (applies when type is "selector"): "css" (default), "xpath", or "text".'),
     timeout: z.number().optional().default(5000).describe('Timeout in milliseconds (default: 5000ms)'),
 });
 export const GetStylesSchema = WindowTargetSchema.extend({
-    selector: z.string().describe('CSS selector for element(s) to get styles from'),
+    selector: z.string().describe('Element selector: CSS selector (default), XPath expression, text content, or ref ID'),
+    strategy: selectorStrategyField,
     properties: z.array(z.string()).optional().describe('Specific CSS properties to retrieve. If omitted, returns all computed styles'),
     multiple: z.boolean().optional().default(false)
         .describe('Whether to get styles for all matching elements (true) or just the first (false)'),
@@ -68,8 +82,9 @@ export const FocusElementSchema = WindowTargetSchema.extend({
     selector: z.string().describe('CSS selector for element to focus'),
 });
 export const FindElementSchema = WindowTargetSchema.extend({
-    selector: z.string(),
-    strategy: z.enum(['css', 'xpath', 'text']).default('css'),
+    selector: z.string().describe('The selector to find: CSS selector (default), XPath expression, text content, or ref ID (e.g., "ref=e3"). ' +
+        'Interpretation depends on strategy.'),
+    strategy: selectorStrategyField,
 });
 export const GetConsoleLogsSchema = WindowTargetSchema.extend({
     filter: z.string().optional().describe('Regex or keyword to filter logs'),
@@ -77,13 +92,14 @@ export const GetConsoleLogsSchema = WindowTargetSchema.extend({
 });
 export const DomSnapshotSchema = WindowTargetSchema.extend({
     type: z.enum(['accessibility', 'structure']).describe('Snapshot type'),
-    selector: z.string().optional().describe('CSS selector to scope the snapshot. If omitted, snapshots entire document.'),
+    selector: z.string().optional().describe('Selector to scope the snapshot: CSS selector (default), XPath, text content, or ref ID. If omitted, snapshots entire document.'),
+    strategy: selectorStrategyField,
 });
 // ============================================================================
 // Implementation Functions
 // ============================================================================
 export async function interact(options) {
-    const { action, selector, x, y, duration, scrollX, scrollY, fromX, fromY, toX, toY, windowId, appIdentifier } = options;
+    const { action, selector, strategy, x, y, duration, scrollX, scrollY, fromX, fromY, toX, toY, windowId, appIdentifier } = options;
     // Handle swipe action separately since it has different logic
     if (action === 'swipe') {
         return performSwipe({ fromX, fromY, toX, toY, duration, windowId, appIdentifier });
@@ -93,11 +109,12 @@ export async function interact(options) {
         if (!selector) {
             throw new Error('Focus action requires a selector');
         }
-        return focusElement({ selector, windowId, appIdentifier });
+        return focusElement({ selector, strategy, windowId, appIdentifier });
     }
     const script = buildScript(SCRIPTS.interact, {
         action,
         selector: selector ?? null,
+        strategy: strategy ?? 'css',
         x: x ?? null,
         y: y ?? null,
         duration: duration ?? 500,
@@ -146,7 +163,7 @@ export async function screenshot(options = {}) {
     return result;
 }
 export async function keyboard(options) {
-    const { action, selectorOrKey, textOrModifiers, modifiers, windowId, appIdentifier } = options;
+    const { action, selectorOrKey, strategy, textOrModifiers, modifiers, windowId, appIdentifier } = options;
     // Handle the different parameter combinations based on action
     if (action === 'type') {
         const selector = selectorOrKey;
@@ -154,7 +171,7 @@ export async function keyboard(options) {
         if (!selector || !text) {
             throw new Error('Type action requires both selector and text parameters');
         }
-        const script = buildTypeScript(selector, text);
+        const script = buildTypeScript(selector, text, strategy);
         try {
             return await executeInWebview(script, windowId, appIdentifier);
         }
@@ -179,8 +196,8 @@ export async function keyboard(options) {
     }
 }
 export async function waitFor(options) {
-    const { type, value, timeout = 5000, windowId, appIdentifier } = options;
-    const script = buildScript(SCRIPTS.waitFor, { type, value, timeout });
+    const { type, value, strategy, timeout = 5000, windowId, appIdentifier } = options;
+    const script = buildScript(SCRIPTS.waitFor, { type, value, strategy: strategy ?? 'css', timeout });
     try {
         return await executeInWebview(script, windowId, appIdentifier);
     }
@@ -190,9 +207,10 @@ export async function waitFor(options) {
     }
 }
 export async function getStyles(options) {
-    const { selector, properties, multiple = false, windowId, appIdentifier } = options;
+    const { selector, strategy, properties, multiple = false, windowId, appIdentifier } = options;
     const script = buildScript(SCRIPTS.getStyles, {
         selector,
+        strategy: strategy ?? 'css',
         properties: properties || [],
         multiple,
     });
@@ -232,8 +250,8 @@ export async function executeJavaScript(options) {
     }
 }
 export async function focusElement(options) {
-    const { selector, windowId, appIdentifier } = options;
-    const script = buildScript(SCRIPTS.focus, { selector });
+    const { selector, strategy, windowId, appIdentifier } = options;
+    const script = buildScript(SCRIPTS.focus, { selector, strategy: strategy ?? 'css' });
     try {
         return await executeInWebview(script, windowId, appIdentifier);
     }
@@ -274,13 +292,13 @@ export async function getConsoleLogs(options = {}) {
  * Uses aria-api for comprehensive, spec-compliant accessibility computation.
  */
 export async function domSnapshot(options) {
-    const { type, selector, windowId, appIdentifier } = options;
+    const { type, selector, strategy, windowId, appIdentifier } = options;
     // Only load aria-api for accessibility snapshots
     if (type === 'accessibility') {
         await ensureAriaApiLoaded(windowId);
     }
     // Then execute the snapshot script
-    const script = buildScript(SCRIPTS.domSnapshot, { type, selector: selector ?? null });
+    const script = buildScript(SCRIPTS.domSnapshot, { type, selector: selector ?? null, strategy: strategy ?? 'css' });
     try {
         return await executeInWebview(script, windowId, appIdentifier);
     }

package/dist/tools-registry.js

@@ -169,6 +169,8 @@ export const TOOLS = [
     {
         name: 'webview_find_element',
         description: '[Tauri Apps Only] Find DOM elements in a running Tauri app\'s webview. ' +
+            'Supports CSS selectors (default), XPath expressions, and text content matching via the strategy parameter. ' +
+            'Returns the element\'s HTML. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +
             'For browser pages or documentation sites, use Chrome DevTools MCP instead.',
@@ -212,6 +214,7 @@ export const TOOLS = [
         name: 'webview_interact',
         description: '[Tauri Apps Only] Click, scroll, swipe, focus, or perform gestures in a Tauri app webview. ' +
             'Supported actions: click, double-click, long-press, scroll, swipe, focus. ' +
+            'Supports CSS selectors (default), XPath, and text content matching via the strategy parameter. ' +
             'Requires active driver_session. ' +
             'For browser interaction, use Chrome DevTools MCP instead.',
         category: TOOL_CATEGORIES.UI_AUTOMATION,
@@ -262,6 +265,8 @@ export const TOOLS = [
     {
         name: 'webview_keyboard',
         description: '[Tauri Apps Only] Type text or send keyboard events in a Tauri app. ' +
+            'The selector parameter (for "type" action) supports CSS selectors (default), ' +
+            'XPath, and text content matching via the strategy parameter. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +
             'For browser keyboard input, use Chrome DevTools MCP instead.',
@@ -279,6 +284,7 @@ export const TOOLS = [
                 return await keyboard({
                     action: parsed.action,
                     selectorOrKey: parsed.selector,
+                    strategy: parsed.strategy,
                     textOrModifiers: parsed.text,
                     windowId: parsed.windowId,
                     appIdentifier: parsed.appIdentifier,
@@ -296,6 +302,7 @@ export const TOOLS = [
     {
         name: 'webview_wait_for',
         description: '[Tauri Apps Only] Wait for elements, text, or IPC events in a Tauri app. ' +
+            'When type is "selector", supports CSS (default), XPath, and text strategies via the strategy parameter. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +
             'For browser waits, use Chrome DevTools MCP instead.',
@@ -311,6 +318,7 @@ export const TOOLS = [
             return await waitFor({
                 type: parsed.type,
                 value: parsed.value,
+                strategy: parsed.strategy,
                 timeout: parsed.timeout,
                 windowId: parsed.windowId,
                 appIdentifier: parsed.appIdentifier,
@@ -320,6 +328,7 @@ export const TOOLS = [
     {
         name: 'webview_get_styles',
         description: '[Tauri Apps Only] Get computed CSS styles from elements in a Tauri app. ' +
+            'Supports CSS selectors (default), XPath, and text content matching via the strategy parameter. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +
             'For browser style inspection, use Chrome DevTools MCP instead.',
@@ -334,6 +343,7 @@ export const TOOLS = [
             const parsed = GetStylesSchema.parse(args);
             return await getStyles({
                 selector: parsed.selector,
+                strategy: parsed.strategy,
                 properties: parsed.properties,
                 multiple: parsed.multiple,
                 windowId: parsed.windowId,
@@ -378,6 +388,7 @@ export const TOOLS = [
             'with element tag names, IDs, CSS classes, and data-testid attributes (if present). ' +
             'Use this for understanding page layout, debugging CSS selectors, or locating elements by class/ID. ' +
             'Use the optional selector parameter to scope the snapshot to a subtree. ' +
+            'The selector supports CSS (default), XPath, and text content matching via the strategy parameter. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC,
         category: TOOL_CATEGORIES.UI_AUTOMATION,
@@ -392,6 +403,7 @@ export const TOOLS = [
             return await domSnapshot({
                 type: parsed.type,
                 selector: parsed.selector,
+                strategy: parsed.strategy,
                 windowId: parsed.windowId,
                 appIdentifier: parsed.appIdentifier,
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypothesi/tauri-mcp-server",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "mcpName": "io.github.hypothesi/mcp-server-tauri",
   "description": "A Model Context Protocol server for use with Tauri v2 applications",
   "type": "module",