@hypothesi/tauri-mcp-server 0.10.0 → 0.11.1

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export declare const SETUP_INSTRUCTIONS: string;

package/dist/constants.js

@@ -0,0 +1,67 @@
+import { PLUGIN_VERSION_CARGO } from './version.js';
+export const SETUP_INSTRUCTIONS = `Help me set up or update the MCP Bridge plugin in my Tauri project.
+
+## IMPORTANT: Do Not Act Without Permission
+
+**You must NOT make any changes to files without my explicit approval.**
+
+1. First, examine my project to understand its current state
+2. Then, present a clear summary of what changes are needed
+3. Wait for my approval before making ANY modifications
+4. Only proceed with changes after I confirm
+
+## Prerequisites Check
+
+First, verify this is a Tauri v2 project:
+- Look for \`src-tauri/\` directory and \`tauri.conf.json\`
+- If this is NOT a Tauri project, stop and let me know this setup only applies to Tauri apps
+
+## What to Check
+
+Examine these files and report what needs to be added or updated:
+
+### 1. Rust Plugin Dependency
+Check \`src-tauri/Cargo.toml\` for \`tauri-plugin-mcp-bridge\`. If missing or outdated, note that it needs:
+\`\`\`toml
+[dependencies]
+tauri-plugin-mcp-bridge = "${PLUGIN_VERSION_CARGO}"
+\`\`\`
+
+### 2. Plugin Registration
+Check \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\` for plugin registration. It should have:
+\`\`\`rust
+#[cfg(debug_assertions)]
+{
+    builder = builder.plugin(tauri_plugin_mcp_bridge::init());
+}
+\`\`\`
+
+### 3. Global Tauri Setting
+Check \`src-tauri/tauri.conf.json\` for \`withGlobalTauri: true\` under the \`app\` section.
+**This is required** - without it, the MCP bridge cannot communicate with the webview.
+
+### 4. Plugin Permissions
+Check \`src-tauri/capabilities/default.json\` (or similar) for \`"mcp-bridge:default"\` permission.
+
+## Your Response Format
+
+After examining the project, respond with:
+
+1. **Current State**: What's already configured correctly
+2. **Changes Needed**: A numbered list of specific changes required
+3. **Ask for Permission**: "May I proceed with these changes?"
+
+Only after I say yes should you make any modifications.
+
+## After Setup
+
+Once changes are approved and made:
+1. Run the Tauri app in development mode (\`cargo tauri dev\`)
+2. Use \`driver_session\` with action "start" to connect
+3. Use \`driver_session\` with action "status" to verify
+
+## Notes
+
+- The plugin only runs in debug builds so it won't affect production
+- The WebSocket server binds to \`0.0.0.0:9223\` by default
+- For localhost-only access, use \`Builder::new().bind_address("127.0.0.1").build()\``;

package/dist/driver/element-picker.js

@@ -10,7 +10,7 @@ import { executeInWebview, executeAsyncInWebview } from './webview-executor.js';
 import { ensureSessionAndConnect } from './plugin-client.js';
 import { SCRIPTS, buildScript } from './scripts/index.js';
 import { WindowTargetSchema } from './webview-interactions.js';
-import { getHtml2CanvasSource, HTML2CANVAS_SCRIPT_ID, } from './scripts/html2canvas-loader.js';
+import { getHtml2CanvasSource, HTML2CANVAS_SCRIPT_ID, HTML2CANVAS_RESOLVER_SCRIPT, HTML2CANVAS_OPTIONS_SCRIPT, } from './scripts/html2canvas-loader.js';
 import { registerScript, isScriptRegistered } from './script-manager.js';
 // ============================================================================
 // Schemas
@@ -99,13 +99,13 @@ async function cleanupPickerHighlights(windowId, appIdentifier) {
  * Capture a screenshot of a specific element using html2canvas.
  * Returns the base64 data URL of the cropped element image, or null on failure.
  */
-async function captureElementScreenshot(cssSelector, windowId) {
+async function captureElementScreenshot(cssSelector, windowId, appIdentifier) {
     // Ensure html2canvas is loaded in the webview
     try {
-        const isRegistered = await isScriptRegistered(HTML2CANVAS_SCRIPT_ID);
+        const isRegistered = await isScriptRegistered(HTML2CANVAS_SCRIPT_ID, appIdentifier);
         if (!isRegistered) {
             const source = getHtml2CanvasSource();
-            await registerScript(HTML2CANVAS_SCRIPT_ID, 'inline', source);
+            await registerScript(HTML2CANVAS_SCRIPT_ID, 'inline', source, windowId, appIdentifier);
         }
     }
     catch {
@@ -114,28 +114,14 @@ async function captureElementScreenshot(cssSelector, windowId) {
     const escapedSelector = cssSelector.replace(/\\/g, '\\\\').replace(/'/g, '\\\'');
     // Build a script that captures just the element with html2canvas
     const captureScript = `
-      const html2canvasFn = typeof html2canvas !== 'undefined' ? html2canvas :
-                           (typeof window !== 'undefined' && window.html2canvas) ? window.html2canvas :
-                           (typeof self !== 'undefined' && self.html2canvas) ? self.html2canvas :
-                           (typeof globalThis !== 'undefined' && globalThis.html2canvas) ? globalThis.html2canvas : null;
-
-      if (!html2canvasFn) {
-         throw new Error('html2canvas not loaded');
-      }
+      ${HTML2CANVAS_RESOLVER_SCRIPT}
 
       const el = document.querySelector('${escapedSelector}');
       if (!el) {
          throw new Error('Element not found for screenshot');
       }
 
-      const canvas = await html2canvasFn(el, {
-         backgroundColor: null,
-         scale: window.devicePixelRatio || 1,
-         logging: false,
-         useCORS: true,
-         allowTaint: false,
-         imageTimeout: 5000,
-      });
+      const canvas = await html2canvasFn(el, ${HTML2CANVAS_OPTIONS_SCRIPT});
 
       if (!canvas) {
          throw new Error('html2canvas returned null canvas');
@@ -149,7 +135,7 @@ async function captureElementScreenshot(cssSelector, windowId) {
       return dataUrl;
    `;
     try {
-        const dataUrl = await executeAsyncInWebview(captureScript, windowId, 10000);
+        const dataUrl = await executeAsyncInWebview(captureScript, windowId, 10000, appIdentifier);
         if (!dataUrl || !dataUrl.startsWith('data:image/')) {
             return null;
         }
@@ -168,6 +154,23 @@ async function captureElementScreenshot(cssSelector, windowId) {
         return null;
     }
 }
+/**
+ * Common helper to format an element and capture its screenshot.
+ */
+async function buildElementContent(element, windowId, appIdentifier) {
+    const content = [];
+    // Add formatted metadata
+    content.push({ type: 'text', text: formatElementMetadata(element) });
+    // Capture element-only screenshot (no picker overlays visible)
+    const screenshot = await captureElementScreenshot(element.cssSelector, windowId, appIdentifier);
+    if (screenshot) {
+        content.push(screenshot);
+    }
+    else {
+        content.push({ type: 'text', text: '(Element screenshot capture failed)' });
+    }
+    return content;
+}
 // ============================================================================
 // selectElement - Agent-initiated picker
 // ============================================================================
@@ -217,18 +220,7 @@ export async function selectElement(options) {
     }
     // Clean up all picker UI BEFORE taking the screenshot
     await cleanupPickerHighlights(windowId, appIdentifier);
-    const content = [];
-    // Add formatted metadata
-    content.push({ type: 'text', text: formatElementMetadata(element) });
-    // Capture element-only screenshot (no picker overlays visible)
-    const screenshot = await captureElementScreenshot(element.cssSelector, windowId);
-    if (screenshot) {
-        content.push(screenshot);
-    }
-    else {
-        content.push({ type: 'text', text: '(Element screenshot capture failed)' });
-    }
-    return content;
+    return buildElementContent(element, windowId, appIdentifier);
 }
 // ============================================================================
 // getPointedElement - Retrieve user-pointed element
@@ -257,16 +249,5 @@ export async function getPointedElement(options) {
     catch {
         return [{ type: 'text', text: `Failed to parse pointed element data: ${raw.substring(0, 200)}` }];
     }
-    const content = [];
-    // Add formatted metadata
-    content.push({ type: 'text', text: formatElementMetadata(element) });
-    // Capture element-only screenshot (no overlays)
-    const screenshot = await captureElementScreenshot(element.cssSelector, windowId);
-    if (screenshot) {
-        content.push(screenshot);
-    }
-    else {
-        content.push({ type: 'text', text: '(Element screenshot capture failed)' });
-    }
-    return content;
+    return buildElementContent(element, windowId, appIdentifier);
 }

package/dist/driver/script-manager.d.ts

@@ -59,7 +59,7 @@ interface GetScriptsResponse {
  * @param windowLabel - Optional window label to target
  * @returns Promise resolving to registration result
  */
-export declare function registerScript(id: string, type: ScriptType, content: string, windowLabel?: string): Promise<RegisterScriptResponse>;
+export declare function registerScript(id: string, type: ScriptType, content: string, windowLabel?: string, appIdentifier?: string | number): Promise<RegisterScriptResponse>;
 /**
  * Removes a script from the registry and DOM.
  *
@@ -67,25 +67,25 @@ export declare function registerScript(id: string, type: ScriptType, content: st
  * @param windowLabel - Optional window label to target
  * @returns Promise resolving to removal result
  */
-export declare function removeScript(id: string, windowLabel?: string): Promise<RemoveScriptResponse>;
+export declare function removeScript(id: string, windowLabel?: string, appIdentifier?: string | number): Promise<RemoveScriptResponse>;
 /**
  * Clears all registered scripts from the registry and DOM.
  *
  * @param windowLabel - Optional window label to target
  * @returns Promise resolving to the number of scripts cleared
  */
-export declare function clearScripts(windowLabel?: string): Promise<ClearScriptsResponse>;
+export declare function clearScripts(windowLabel?: string, appIdentifier?: string | number): Promise<ClearScriptsResponse>;
 /**
  * Gets all registered scripts.
  *
  * @returns Promise resolving to the list of registered scripts
  */
-export declare function getScripts(): Promise<GetScriptsResponse>;
+export declare function getScripts(appIdentifier?: string | number): Promise<GetScriptsResponse>;
 /**
  * Checks if a script with the given ID is registered.
  *
  * @param id - The script ID to check
  * @returns Promise resolving to true if the script is registered
  */
-export declare function isScriptRegistered(id: string): Promise<boolean>;
+export declare function isScriptRegistered(id: string, appIdentifier?: string | number): Promise<boolean>;
 export {};

package/dist/driver/script-manager.js

@@ -19,8 +19,8 @@ import { ensureSessionAndConnect } from './plugin-client.js';
  * @param windowLabel - Optional window label to target
  * @returns Promise resolving to registration result
  */
-export async function registerScript(id, type, content, windowLabel) {
-    const client = await ensureSessionAndConnect();
+export async function registerScript(id, type, content, windowLabel, appIdentifier) {
+    const client = await ensureSessionAndConnect(appIdentifier);
     const response = await client.sendCommand({
         command: 'register_script',
         args: { id, type, content, windowLabel },
@@ -37,8 +37,8 @@ export async function registerScript(id, type, content, windowLabel) {
  * @param windowLabel - Optional window label to target
  * @returns Promise resolving to removal result
  */
-export async function removeScript(id, windowLabel) {
-    const client = await ensureSessionAndConnect();
+export async function removeScript(id, windowLabel, appIdentifier) {
+    const client = await ensureSessionAndConnect(appIdentifier);
     const response = await client.sendCommand({
         command: 'remove_script',
         args: { id, windowLabel },
@@ -54,8 +54,8 @@ export async function removeScript(id, windowLabel) {
  * @param windowLabel - Optional window label to target
  * @returns Promise resolving to the number of scripts cleared
  */
-export async function clearScripts(windowLabel) {
-    const client = await ensureSessionAndConnect();
+export async function clearScripts(windowLabel, appIdentifier) {
+    const client = await ensureSessionAndConnect(appIdentifier);
     const response = await client.sendCommand({
         command: 'clear_scripts',
         args: { windowLabel },
@@ -70,8 +70,8 @@ export async function clearScripts(windowLabel) {
  *
  * @returns Promise resolving to the list of registered scripts
  */
-export async function getScripts() {
-    const client = await ensureSessionAndConnect();
+export async function getScripts(appIdentifier) {
+    const client = await ensureSessionAndConnect(appIdentifier);
     const response = await client.sendCommand({
         command: 'get_scripts',
         args: {},
@@ -87,7 +87,7 @@ export async function getScripts() {
  * @param id - The script ID to check
  * @returns Promise resolving to true if the script is registered
  */
-export async function isScriptRegistered(id) {
-    const { scripts } = await getScripts();
+export async function isScriptRegistered(id, appIdentifier) {
+    const { scripts } = await getScripts(appIdentifier);
     return scripts.some((s) => { return s.id === id; });
 }

package/dist/driver/scripts/html2canvas-loader.d.ts

@@ -13,6 +13,8 @@ export declare const HTML2CANVAS_SCRIPT_ID = "__mcp_html2canvas__";
  * Loaded lazily and cached.
  */
 export declare function getHtml2CanvasSource(): string;
+export declare const HTML2CANVAS_RESOLVER_SCRIPT = "\n      // Get the html2canvas function (may be on window, self, or globalThis)\n      const html2canvasFn = typeof html2canvas !== 'undefined' ? html2canvas :\n                           (typeof window !== 'undefined' && window.html2canvas) ? window.html2canvas :\n                           (typeof self !== 'undefined' && self.html2canvas) ? self.html2canvas :\n                           (typeof globalThis !== 'undefined' && globalThis.html2canvas) ? globalThis.html2canvas : null;\n\n      if (!html2canvasFn) {\n         throw new Error('html2canvas not loaded');\n      }\n";
+export declare const HTML2CANVAS_OPTIONS_SCRIPT = "{\n         backgroundColor: null,\n         scale: window.devicePixelRatio || 1,\n         logging: false,\n         useCORS: true,\n         allowTaint: false,\n         imageTimeout: 5000,\n      }";
 /**
  * Build a script that captures a screenshot using html2canvas.
  * Assumes html2canvas is already loaded (either via script manager or inline).

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

@@ -30,13 +30,7 @@ export function getHtml2CanvasSource() {
     }
     return html2canvasProSource;
 }
-/**
- * Build a script that captures a screenshot using html2canvas.
- * Assumes html2canvas is already loaded (either via script manager or inline).
- */
-export function buildScreenshotCaptureScript(format, quality) {
-    // Note: This script is wrapped by executeAsyncInWebview, so we don't need an IIFE
-    return `
+export const HTML2CANVAS_RESOLVER_SCRIPT = `
       // Get the html2canvas function (may be on window, self, or globalThis)
       const html2canvasFn = typeof html2canvas !== 'undefined' ? html2canvas :
                            (typeof window !== 'undefined' && window.html2canvas) ? window.html2canvas :
@@ -44,27 +38,34 @@ export function buildScreenshotCaptureScript(format, quality) {
                            (typeof globalThis !== 'undefined' && globalThis.html2canvas) ? globalThis.html2canvas : null;
 
       if (!html2canvasFn) {
-         throw new Error('html2canvas not loaded - function not found on any global');
+         throw new Error('html2canvas not loaded');
       }
-
-      // Capture the entire document
-      const element = document.documentElement;
-      if (!element) {
-         throw new Error('document.documentElement is null');
-      }
-
-      // Configure html2canvas options
-      const options = {
+`;
+export const HTML2CANVAS_OPTIONS_SCRIPT = `{
          backgroundColor: null,
          scale: window.devicePixelRatio || 1,
          logging: false,
          useCORS: true,
          allowTaint: false,
          imageTimeout: 5000,
-      };
+      }`;
+/**
+ * Build a script that captures a screenshot using html2canvas.
+ * Assumes html2canvas is already loaded (either via script manager or inline).
+ */
+export function buildScreenshotCaptureScript(format, quality) {
+    // Note: This script is wrapped by executeAsyncInWebview, so we don't need an IIFE
+    return `
+      ${HTML2CANVAS_RESOLVER_SCRIPT}
+
+      // Capture the entire document
+      const element = document.documentElement;
+      if (!element) {
+         throw new Error('document.documentElement is null');
+      }
 
       // Capture the webview
-      const canvas = await html2canvasFn(element, options);
+      const canvas = await html2canvasFn(element, ${HTML2CANVAS_OPTIONS_SCRIPT});
       if (!canvas) {
          throw new Error('html2canvas returned null canvas');
       }

package/dist/driver/scripts/index.js

@@ -56,8 +56,24 @@ export function buildTypeScript(selector, text, strategy) {
          if (!element) throw new Error('Element not found: ' + selector);
 
          element.focus();
-         element.value = text;
-         element.dispatchEvent(new Event('input', { bubbles: true }));
+
+         // Use native prototype setter to bypass React's value tracker
+         var proto = element.tagName === 'TEXTAREA'
+            ? HTMLTextAreaElement.prototype
+            : HTMLInputElement.prototype;
+         var descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
+
+         if (descriptor && descriptor.set) {
+            descriptor.set.call(element, text);
+         } else {
+            element.value = text;
+         }
+
+         // Reset React's internal value tracker so it detects the change
+         if (element._valueTracker) element._valueTracker.setValue('');
+
+         // Dispatch proper InputEvent (not generic Event) for React compatibility
+         element.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'insertText', data: text }));
          element.dispatchEvent(new Event('change', { bubbles: true }));
 
          var msg = 'Typed "' + text + '" into ' + selector;
@@ -90,17 +106,20 @@ export function buildKeyEventScript(action, key, modifiers = []) {
 
          const activeElement = document.activeElement || document.body;
 
+         const modStr = modifiers.length ? ' with ' + modifiers.join('+') : '';
+         const dispatch = (type) => activeElement.dispatchEvent(new KeyboardEvent(type, eventOptions));
+
          if (action === 'press') {
-            activeElement.dispatchEvent(new KeyboardEvent('keydown', eventOptions));
-            activeElement.dispatchEvent(new KeyboardEvent('keypress', eventOptions));
-            activeElement.dispatchEvent(new KeyboardEvent('keyup', eventOptions));
-            return 'Pressed key: ' + key + (modifiers.length ? ' with ' + modifiers.join('+') : '');
+            dispatch('keydown');
+            dispatch('keypress');
+            dispatch('keyup');
+            return 'Pressed key: ' + key + modStr;
          } else if (action === 'down') {
-            activeElement.dispatchEvent(new KeyboardEvent('keydown', eventOptions));
-            return 'Key down: ' + key + (modifiers.length ? ' with ' + modifiers.join('+') : '');
+            dispatch('keydown');
+            return 'Key down: ' + key + modStr;
          } else if (action === 'up') {
-            activeElement.dispatchEvent(new KeyboardEvent('keyup', eventOptions));
-            return 'Key up: ' + key + (modifiers.length ? ' with ' + modifiers.join('+') : '');
+            dispatch('keyup');
+            return 'Key up: ' + key + modStr;
          }
 
          throw new Error('Unknown action: ' + action);

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

@@ -47,9 +47,22 @@
       }
 
       if (strategy === 'text') {
+         // First try: match element text content
          var xpath = xpathForText(selectorOrRef);
          var result = document.evaluate(xpath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
-         return result.singleNodeValue;
+         if (result.singleNodeValue) return result.singleNodeValue;
+
+         // Fallback: search placeholder, aria-label, and title attributes
+         var attrSelectors = [
+            '[placeholder*="' + selectorOrRef.replace(/"/g, '\\"') + '"]',
+            '[aria-label*="' + selectorOrRef.replace(/"/g, '\\"') + '"]',
+            '[title*="' + selectorOrRef.replace(/"/g, '\\"') + '"]',
+         ];
+         for (var i = 0; i < attrSelectors.length; i++) {
+            var el = document.querySelector(attrSelectors[i]);
+            if (el) return el;
+         }
+         return null;
       }
 
       if (strategy === 'xpath') {
@@ -78,12 +91,25 @@
       }
 
       if (strategy === 'text') {
+         // First try: match element text content
          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));
          }
+         if (results.length > 0) return results;
+
+         // Fallback: search placeholder, aria-label, and title attributes
+         var attrSelectors = [
+            '[placeholder*="' + selector.replace(/"/g, '\\"') + '"]',
+            '[aria-label*="' + selector.replace(/"/g, '\\"') + '"]',
+            '[title*="' + selector.replace(/"/g, '\\"') + '"]',
+         ];
+         for (var i = 0; i < attrSelectors.length; i++) {
+            var found = Array.from(document.querySelectorAll(attrSelectors[i]));
+            if (found.length > 0) return results.concat(found);
+         }
          return results;
       }
 

package/dist/driver/webview-executor.d.ts

@@ -12,7 +12,7 @@ import { z } from 'zod';
  *
  * @throws Error if no session is active (driver_session must be called first)
  */
-export declare function ensureReady(): Promise<void>;
+export declare function ensureReady(windowId?: string, appIdentifier?: string | number): Promise<void>;
 /**
  * Reset initialization state (useful for testing or reconnecting).
  */
@@ -48,7 +48,7 @@ export declare function executeInWebviewWithContext(script: string, windowId?: s
  * @param timeout - Timeout in milliseconds (default: 5000)
  * @returns Result of the script execution
  */
-export declare function executeAsyncInWebview(script: string, windowId?: string, timeout?: number): Promise<string>;
+export declare function executeAsyncInWebview(script: string, windowId?: string, timeout?: number, appIdentifier?: string | number): Promise<string>;
 /**
  * Initialize console log capture in the webview.
  * This intercepts console methods and stores logs in memory.

package/dist/driver/webview-executor.js

@@ -1,6 +1,5 @@
 import { z } from 'zod';
-import { connectPlugin } from './plugin-client.js';
-import { hasActiveSession, getDefaultSession, resolveTargetApp } from './session-manager.js';
+import { hasActiveSession, resolveTargetApp, manageDriverSession } from './session-manager.js';
 import { createMcpLogger } from '../logger.js';
 import { buildScreenshotScript, buildScreenshotCaptureScript, getHtml2CanvasSource, HTML2CANVAS_SCRIPT_ID, } from './scripts/html2canvas-loader.js';
 import { registerScript, isScriptRegistered } from './script-manager.js';
@@ -17,7 +16,7 @@ import { getResolveRefSource, RESOLVE_REF_SCRIPT_ID } from './scripts/index.js';
 // ============================================================================
 // Auto-Initialization System
 // ============================================================================
-let isInitialized = false;
+const initializedTargets = new Set();
 const driverLogger = createMcpLogger('DRIVER');
 /**
  * Ensures the MCP server is fully initialized and ready to use.
@@ -32,28 +31,52 @@ const driverLogger = createMcpLogger('DRIVER');
  *
  * @throws Error if no session is active (driver_session must be called first)
  */
-export async function ensureReady() {
-    if (isInitialized) {
-        return;
-    }
-    // Require an active session to prevent connecting to wrong app
+export async function ensureReady(windowId, appIdentifier) {
+    // Auto-connect if no active session
     if (!hasActiveSession()) {
-        throw new Error('No active session. Call driver_session with action "start" first to connect to a Tauri app.');
+        const result = await manageDriverSession('start');
+        if (!hasActiveSession()) {
+            throw new Error('Auto-connect failed: ' + result + '. Call driver_session with action "start" to connect manually.');
+        }
     }
-    // Get default session for initial connection
-    const session = getDefaultSession();
-    if (session) {
-        await connectPlugin(session.host, session.port);
+    const session = resolveTargetApp(appIdentifier);
+    if (!session.client.isConnected()) {
+        await session.client.connect();
     }
-    // Register the resolve-ref helper so ref-based selectors work in all tools
-    await registerScript(RESOLVE_REF_SCRIPT_ID, 'inline', getResolveRefSource());
-    isInitialized = true;
+    const targetKey = `${session.host}:${session.port}:${windowId ?? 'main'}`;
+    if (initializedTargets.has(targetKey)) {
+        return;
+    }
+    // Register the resolve-ref helper in the target window
+    // so ref-based selectors work there.
+    await registerScript(RESOLVE_REF_SCRIPT_ID, 'inline', getResolveRefSource(), windowId, appIdentifier);
+    await waitForResolveRefHelper(session, windowId);
+    initializedTargets.add(targetKey);
 }
 /**
  * Reset initialization state (useful for testing or reconnecting).
  */
 export function resetInitialization() {
-    isInitialized = false;
+    initializedTargets.clear();
+}
+async function waitForResolveRefHelper(session, windowId) {
+    if (!session) {
+        throw new Error('No active session available while registering resolve-ref helper.');
+    }
+    for (let attempt = 0; attempt < 20; attempt++) {
+        const response = await session.client.sendCommand({
+            command: 'execute_js',
+            args: {
+                script: 'return !!(window.__MCP__ && typeof window.__MCP__.resolveRef === "function")',
+                windowLabel: windowId,
+            },
+        }, 2000);
+        if (response.success && response.data === true) {
+            return;
+        }
+        await new Promise((resolve) => { return setTimeout(resolve, 50); });
+    }
+    throw new Error('Resolve-ref helper was not available in the webview after registration.');
 }
 /**
  * Execute JavaScript in the Tauri webview using native IPC via WebSocket.
@@ -78,7 +101,7 @@ export async function executeInWebview(script, windowId, appIdentifier) {
 export async function executeInWebviewWithContext(script, windowId, appIdentifier) {
     try {
         // Ensure we're fully initialized
-        await ensureReady();
+        await ensureReady(windowId, appIdentifier);
         // Resolve target session
         const session = resolveTargetApp(appIdentifier);
         const client = session.client;
@@ -124,11 +147,12 @@ export async function executeInWebviewWithContext(script, windowId, appIdentifie
  * @param timeout - Timeout in milliseconds (default: 5000)
  * @returns Result of the script execution
  */
-export async function executeAsyncInWebview(script, windowId, timeout = 5000) {
+export async function executeAsyncInWebview(script, windowId, timeout, appIdentifier) {
+    const resolvedTimeout = timeout ?? 5000;
     const wrappedScript = `
       return (async () => {
          const timeoutPromise = new Promise((_, reject) => {
-            setTimeout(() => reject(new Error('Script execution timeout')), ${timeout});
+            setTimeout(() => reject(new Error('Script execution timeout')), ${resolvedTimeout});
          });
 
          const scriptPromise = (async () => {
@@ -138,7 +162,7 @@ export async function executeAsyncInWebview(script, windowId, timeout = 5000) {
          return await Promise.race([scriptPromise, timeoutPromise]);
       })();
    `;
-    return executeInWebview(wrappedScript, windowId);
+    return executeInWebview(wrappedScript, windowId, appIdentifier);
 }
 // ============================================================================
 // Console Log Capture System
@@ -268,14 +292,14 @@ function buildScreenshotResult(dataUrl, method, windowContext) {
  * Prepares the html2canvas script for screenshot capture.
  * Tries to use the script manager for persistence, falls back to inline injection.
  */
-async function prepareHtml2canvasScript(format, quality) {
+async function prepareHtml2canvasScript(format, quality, windowId, appIdentifier) {
     try {
         // Check if html2canvas is already registered
-        const isRegistered = await isScriptRegistered(HTML2CANVAS_SCRIPT_ID);
+        const isRegistered = await isScriptRegistered(HTML2CANVAS_SCRIPT_ID, appIdentifier);
         if (!isRegistered) {
             // Register html2canvas via script manager for persistence across navigations
             const html2canvasSource = getHtml2CanvasSource();
-            await registerScript(HTML2CANVAS_SCRIPT_ID, 'inline', html2canvasSource);
+            await registerScript(HTML2CANVAS_SCRIPT_ID, 'inline', html2canvasSource, windowId, appIdentifier);
         }
         // Use the capture-only script since html2canvas is now registered
         return buildScreenshotCaptureScript(format, quality);
@@ -299,7 +323,7 @@ export async function captureScreenshot(options = {}) {
     // - Linux: Chromium/WebKit screenshot APIs
     try {
         // Ensure we're fully initialized
-        await ensureReady();
+        await ensureReady(windowId, appIdentifier);
         // Resolve target session
         const session = resolveTargetApp(appIdentifier);
         const client = session.client;
@@ -331,7 +355,7 @@ export async function captureScreenshot(options = {}) {
     }
     // Fallback 1: Use html2canvas library for high-quality DOM rendering
     // Try to use the script manager to register html2canvas for persistence
-    const html2canvasScript = await prepareHtml2canvasScript(format, quality);
+    const html2canvasScript = await prepareHtml2canvasScript(format, quality, windowId, appIdentifier);
     // Fallback: Try Screen Capture API if available
     // Note: This script is wrapped by executeAsyncInWebview, so we don't need an IIFE
     const screenCaptureScript = `
@@ -390,7 +414,7 @@ export async function captureScreenshot(options = {}) {
    `;
     try {
         // Try html2canvas second (after native APIs)
-        const result = await executeAsyncInWebview(html2canvasScript, undefined, 10000); // Longer timeout for library loading
+        const result = await executeAsyncInWebview(html2canvasScript, windowId, 10000, appIdentifier);
         // Validate that we got a real data URL, not 'null' or empty
         if (result && result !== 'null' && result.startsWith('data:image/')) {
             return buildScreenshotResult(result, 'html2canvas');
@@ -400,7 +424,7 @@ export async function captureScreenshot(options = {}) {
     catch (html2canvasError) {
         try {
             // Fallback to Screen Capture API
-            const result = await executeAsyncInWebview(screenCaptureScript);
+            const result = await executeAsyncInWebview(screenCaptureScript, windowId, 5000, appIdentifier);
             // Validate that we got a real data URL
             if (result && result.startsWith('data:image/')) {
                 return buildScreenshotResult(result, 'Screen Capture API');

package/dist/driver/webview-interactions.js

@@ -22,7 +22,8 @@ export const WindowTargetSchema = z.object({
  * 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.');
+    '"text" to find elements by text content, with fallback to placeholder, aria-label, ' +
+    'and title attributes. Ref IDs (e.g., "ref=e3") work with any strategy.');
 // ============================================================================
 // Schemas
 // ============================================================================
@@ -154,10 +155,8 @@ export async function screenshot(options = {}) {
         if (!imageContent || imageContent.type !== 'image') {
             throw new Error('Screenshot capture failed: no image data');
         }
-        // Decode base64 and write to file
-        const buffer = Buffer.from(imageContent.data, 'base64');
         const resolvedPath = resolve(filePath);
-        await writeFile(resolvedPath, buffer);
+        await writeFile(resolvedPath, imageContent.data, 'base64');
         return { filePath: resolvedPath, format };
     }
     return result;
@@ -295,7 +294,7 @@ export async function domSnapshot(options) {
     const { type, selector, strategy, windowId, appIdentifier } = options;
     // Only load aria-api for accessibility snapshots
     if (type === 'accessibility') {
-        await ensureAriaApiLoaded(windowId);
+        await ensureAriaApiLoaded(windowId, appIdentifier);
     }
     // Then execute the snapshot script
     const script = buildScript(SCRIPTS.domSnapshot, { type, selector: selector ?? null, strategy: strategy ?? 'css' });
@@ -311,11 +310,11 @@ export async function domSnapshot(options) {
  * Ensure aria-api library is loaded in the webview.
  * Uses the script manager to inject the library if not already present.
  */
-async function ensureAriaApiLoaded(windowId) {
+async function ensureAriaApiLoaded(windowId, appIdentifier) {
     const { getAriaApiSource, ARIA_API_SCRIPT_ID: ariaApiScriptId } = await import('./scripts/aria-api-loader.js');
     const { registerScript, isScriptRegistered } = await import('./script-manager.js');
-    if (await isScriptRegistered(ariaApiScriptId)) {
+    if (await isScriptRegistered(ariaApiScriptId, appIdentifier)) {
         return;
     }
-    await registerScript(ariaApiScriptId, 'inline', getAriaApiSource(), windowId);
+    await registerScript(ariaApiScriptId, 'inline', getAriaApiSource(), windowId, appIdentifier);
 }

package/dist/prompts-registry.js

@@ -2,7 +2,7 @@
  * Single source of truth for all MCP prompt definitions
  * Prompts are user-controlled templates that appear as slash commands in MCP clients
  */
-import { PLUGIN_VERSION_CARGO } from './version.js';
+import { SETUP_INSTRUCTIONS as SETUP_PROMPT } from './constants.js';
 const FIX_WEBVIEW_ERRORS_PROMPT = `I need help finding and fixing JavaScript errors in my Tauri app's webview.
 
 Please follow these steps:
@@ -25,72 +25,6 @@ Please follow these steps:
 If no errors are found, let me know the app is running cleanly.
 
 If the session fails to start, help me troubleshoot the connection (is the app running? is the MCP bridge plugin installed?).`;
-const SETUP_PROMPT = `Help me set up or update the MCP Bridge plugin in my Tauri project.
-
-## IMPORTANT: Do Not Act Without Permission
-
-**You must NOT make any changes to files without my explicit approval.**
-
-1. First, examine my project to understand its current state
-2. Then, present a clear summary of what changes are needed
-3. Wait for my approval before making ANY modifications
-4. Only proceed with changes after I confirm
-
-## Prerequisites Check
-
-First, verify this is a Tauri v2 project:
-- Look for \`src-tauri/\` directory and \`tauri.conf.json\`
-- If this is NOT a Tauri project, stop and let me know this setup only applies to Tauri apps
-
-## What to Check
-
-Examine these files and report what needs to be added or updated:
-
-### 1. Rust Plugin Dependency
-Check \`src-tauri/Cargo.toml\` for \`tauri-plugin-mcp-bridge\`. If missing or outdated, note that it needs:
-\`\`\`toml
-[dependencies]
-tauri-plugin-mcp-bridge = "${PLUGIN_VERSION_CARGO}"
-\`\`\`
-
-### 2. Plugin Registration
-Check \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\` for plugin registration. It should have:
-\`\`\`rust
-#[cfg(debug_assertions)]
-{
-    builder = builder.plugin(tauri_plugin_mcp_bridge::init());
-}
-\`\`\`
-
-### 3. Global Tauri Setting
-Check \`src-tauri/tauri.conf.json\` for \`withGlobalTauri: true\` under the \`app\` section.
-**This is required** - without it, the MCP bridge cannot communicate with the webview.
-
-### 4. Plugin Permissions
-Check \`src-tauri/capabilities/default.json\` (or similar) for \`"mcp-bridge:default"\` permission.
-
-## Your Response Format
-
-After examining the project, respond with:
-
-1. **Current State**: What's already configured correctly
-2. **Changes Needed**: A numbered list of specific changes required
-3. **Ask for Permission**: "May I proceed with these changes?"
-
-Only after I say yes should you make any modifications.
-
-## After Setup
-
-Once changes are approved and made:
-1. Run the Tauri app in development mode (\`cargo tauri dev\`)
-2. Use \`driver_session\` with action "start" to connect
-3. Use \`driver_session\` with action "status" to verify
-
-## Notes
-
-- The plugin only runs in debug builds so it won't affect production
-- The WebSocket server binds to \`0.0.0.0:9223\` by default
-- For localhost-only access, use \`Builder::new().bind_address("127.0.0.1").build()\``;
 const SELECT_ELEMENT_PROMPT = (message) => {
     const lines = [
         'The user wants to visually select an element in their running Tauri app so they can discuss it with you.',

package/dist/tools-registry.js

@@ -9,7 +9,7 @@ import { readLogs, ReadLogsSchema } from './monitor/logs.js';
 import { executeIPCCommand, manageIPCMonitoring, getIPCEvents, emitTestEvent, getBackendState, manageWindow, ExecuteIPCCommandSchema, ManageIPCMonitoringSchema, GetIPCEventsSchema, EmitTestEventSchema, GetBackendStateSchema, ManageWindowSchema, } from './driver/plugin-commands.js';
 import { interact, screenshot, keyboard, waitFor, getStyles, executeJavaScript, findElement, domSnapshot, InteractSchema, ScreenshotSchema, KeyboardSchema, WaitForSchema, GetStylesSchema, ExecuteJavaScriptSchema, FindElementSchema, DomSnapshotSchema, } from './driver/webview-interactions.js';
 import { selectElement, getPointedElement, SelectElementSchema, GetPointedElementSchema, } from './driver/element-picker.js';
-import { PLUGIN_VERSION_CARGO } from './version.js';
+import { SETUP_INSTRUCTIONS } from './constants.js';
 /**
  * Standard multi-app description for webview tools.
  */
@@ -24,76 +24,6 @@ export const TOOL_CATEGORIES = {
     UI_AUTOMATION: 'UI Automation & WebView Interaction',
     IPC_PLUGIN: 'IPC & Plugin Tools (via MCP Bridge)',
 };
-// Setup instructions for the MCP Bridge plugin
-const SETUP_INSTRUCTIONS = `# MCP Bridge Plugin Setup Instructions
-
-Use these instructions to set up or update the MCP Bridge plugin in a Tauri v2 project.
-
-## IMPORTANT: Do Not Act Without Permission
-
-**You must NOT make any changes to files without the user's explicit approval.**
-
-1. First, examine the project to understand its current state
-2. Then, present a clear summary of what changes are needed
-3. Wait for user approval before making ANY modifications
-4. Only proceed with changes after they confirm
-
-## Prerequisites Check
-
-First, verify this is a Tauri v2 project:
-- Look for \`src-tauri/\` directory and \`tauri.conf.json\`
-- If this is NOT a Tauri project, stop and let the user know this setup only applies to Tauri apps
-
-## What to Check
-
-Examine these files and report what needs to be added or updated:
-
-### 1. Rust Plugin Dependency
-Check \`src-tauri/Cargo.toml\` for \`tauri-plugin-mcp-bridge\`. If missing or outdated, note that it needs:
-\`\`\`toml
-[dependencies]
-tauri-plugin-mcp-bridge = "${PLUGIN_VERSION_CARGO}"
-\`\`\`
-
-### 2. Plugin Registration
-Check \`src-tauri/src/lib.rs\` or \`src-tauri/src/main.rs\` for plugin registration. It should have:
-\`\`\`rust
-#[cfg(debug_assertions)]
-{
-    builder = builder.plugin(tauri_plugin_mcp_bridge::init());
-}
-\`\`\`
-
-### 3. Global Tauri Setting
-Check \`src-tauri/tauri.conf.json\` for \`withGlobalTauri: true\` under the \`app\` section.
-**This is required** - without it, the MCP bridge cannot communicate with the webview.
-
-### 4. Plugin Permissions
-Check \`src-tauri/capabilities/default.json\` (or similar) for \`"mcp-bridge:default"\` permission.
-
-## Response Format
-
-After examining the project, respond with:
-
-1. **Current State**: What's already configured correctly
-2. **Changes Needed**: A numbered list of specific changes required
-3. **Ask for Permission**: "May I proceed with these changes?"
-
-Only after the user says yes should you make any modifications.
-
-## After Setup
-
-Once changes are approved and made:
-1. Run the Tauri app in development mode (\`cargo tauri dev\`)
-2. Use \`driver_session\` with action "start" to connect
-3. Use \`driver_session\` with action "status" to verify
-
-## Notes
-
-- The plugin only runs in debug builds so it won't affect production
-- The WebSocket server binds to \`0.0.0.0:9223\` by default
-- For localhost-only access, use \`Builder::new().bind_address("127.0.0.1").build()\`
-`;
 /**
  * Complete registry of all available tools
  * This is the single source of truth for tool definitions
@@ -171,6 +101,7 @@ 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. ' +
+            'The "text" strategy first searches element text content, then falls back to placeholder, aria-label, and title attributes. ' +
             'Returns the element\'s HTML. ' +
             'Requires active driver_session. ' +
             MULTI_APP_DESC + ' ' +

package/package.json

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