ucu-mcp 0.4.0 → 0.4.2

package/dist/src/platform/macos.js

@@ -4,9 +4,11 @@ import { promisify } from "node:util";
 import { captureFullScreen, captureRegion } from "../utils/screenshot.js";
 import { click as inputClick, doubleClick as inputDoubleClick, move as inputMove, drag as inputDrag, scroll as inputScroll, typeText, pressShortcut } from "../utils/input.js";
 import { CaptureError, ElementNotFoundError, InputSynthesisError, PermissionError, PlatformError, TargetStaleError, UcuError, WindowNotFoundError } from "../util/errors.js";
+import { logger } from "../util/logger.js";
 import { existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { jxaChildElements, jxaGetBounds, jxaIsVisible, jxaElementActionHelpers } from "./jxa-helpers.js";
 const __macosDirname = dirname(fileURLToPath(import.meta.url));
 const execFileAsync = promisify(execFile);
 function errorMessage(error) {
@@ -149,8 +151,9 @@ export class MacOSPlatform {
             return;
         try {
             const { appName } = this.savedFocus;
+            const appNameLiteral = JSON.stringify(appName);
             execFileSync("osascript", [
-                "-e", `tell application "${appName}" to activate`,
+                "-e", `tell application ${appNameLiteral} to activate`,
             ], { timeout: 5000 });
         }
         catch {
@@ -195,8 +198,9 @@ export class MacOSPlatform {
             ], { encoding: "utf-8", timeout: 5000 }).trim();
             return JSON.parse(out);
         }
-        catch {
-            return { width: 1920, height: 1080, scaleFactor: 2 };
+        catch (error) {
+            logger.warn("getScreenSize failed, using fallback", { error: errorMessage(error) });
+            return { width: 1920, height: 1080, scaleFactor: 2, estimated: true };
         }
     }
     isScreenLocked() {
@@ -208,7 +212,8 @@ export class MacOSPlatform {
             return /"IOConsoleLocked"\s*=\s*Yes/.test(out);
         }
         catch {
-            return false;
+            // Fail-closed: if we can't determine lock state, assume locked
+            return true;
         }
     }
     // ── Window Management ───────────────────────────────────────────────────
@@ -235,14 +240,19 @@ export class MacOSPlatform {
       }
       JSON.stringify(result);
     `;
-        const out = execFileSync("osascript", [
-            "-l", "JavaScript",
-            "-e", jxaScript,
-        ], { encoding: "utf-8", timeout: 10000 }).trim();
-        return JSON.parse(out);
+        try {
+            const out = execFileSync("osascript", [
+                "-l", "JavaScript",
+                "-e", jxaScript,
+            ], { encoding: "utf-8", timeout: 10000 }).trim();
+            return JSON.parse(out);
+        }
+        catch (error) {
+            rethrowAccessibilityError(error, "list_apps");
+        }
     }
     async focusApp(app) {
-        const escapedApp = app.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        const appLiteral = JSON.stringify(app);
         this.windowCache = undefined;
         // NOTE: We intentionally do NOT call AppleScript "activate" here.
         // focus_app sets the internal target context so subsequent operations
@@ -269,16 +279,14 @@ export class MacOSPlatform {
             // bare WindowNotFoundError("CC Switch") was indistinguishable from
             // "the app is not running", which led models to retry forever.
             this.activeTarget = undefined; // Clear stale target on focus failure
-            const err = new WindowNotFoundError(app);
-            err.hint =
-                "list_windows returned no match for this app. If the app is running, " +
+            const err = new WindowNotFoundError(app, { hint: "list_windows returned no match for this app. If the app is running, " +
                     "the most likely cause is that it is an Electron app whose AX tree is " +
                     "not exposed to System Events (System Settings > Privacy & Security > " +
                     "Accessibility must be granted to the Electron process itself, not just " +
                     "to the host terminal). Pixel-level workaround: call screenshot to " +
                     "capture the screen, then ocr to locate UI text and get its bounding " +
                     "box coordinates, then click(x, y) at those screen coordinates. " +
-                    "Alternatively, modify the app's config file or database directly.";
+                    "Alternatively, modify the app's config file or database directly." });
             throw err;
         }
         this.activeTarget = {
@@ -308,10 +316,10 @@ export class MacOSPlatform {
         ].some((name) => normalized.includes(name));
         if (!knownBrowser)
             return undefined;
-        const escapedApp = appName.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        const appLiteral = JSON.stringify(appName);
         const jxaScript = `
       function run() {
-        var appName = "${escapedApp}";
+        var appName = ${appLiteral};
         try {
           var app = Application(appName);
           var url = "";
@@ -468,11 +476,16 @@ export class MacOSPlatform {
         }
         JSON.stringify(result);
       `;
-        const jxaOut = execFileSync("osascript", [
-            "-l", "JavaScript",
-            "-e", jxaScript
-        ], { encoding: "utf-8", timeout: 15000 });
-        return JSON.parse(jxaOut.trim());
+        try {
+            const jxaOut = execFileSync("osascript", [
+                "-l", "JavaScript",
+                "-e", jxaScript
+            ], { encoding: "utf-8", timeout: 15000 });
+            return JSON.parse(jxaOut.trim());
+        }
+        catch (error) {
+            rethrowAccessibilityError(error, "list_windows_jxa");
+        }
     }
     async getWindowState(windowId, depth, includeBounds = true) {
         if (!windowId || windowId === this.activeTarget?.windowId) {
@@ -484,18 +497,14 @@ export class MacOSPlatform {
         }
         const maxDepth = Math.min(depth || 3, 10);
         const maxElements = 50;
-        const escapedWindowId = resolvedWindowId.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+        const windowIdLiteral = JSON.stringify(resolvedWindowId);
         const targetWindow = (await this.listWindows(true)).find((w) => w.id === resolvedWindowId);
         const targetJson = JSON.stringify(targetWindow ?? null);
         try {
             const jxaScript = `
         ObjC.import('AppKit');
         var se = Application('System Events');
-      function childElements(elem) {
-        try { return elem.uiElements(); } catch(e1) {
-          try { return elem.elements(); } catch(e2) { return []; }
-        }
-      }
+        ${jxaChildElements()}
         var result = {window: null, focusedElement: null, tree: null, error: null};
         var target = ${targetJson};
         var includeBounds = ${includeBounds ? "true" : "false"};
@@ -506,7 +515,7 @@ export class MacOSPlatform {
 
         function windowMatches(win, proc) {
           if (!target) {
-            try { return String(win.id()) === String("${escapedWindowId}"); } catch(e) { return false; }
+            try { return String(win.id()) === String(${windowIdLiteral}); } catch(e) { return false; }
           }
           try {
             if (target.pid && proc.unixId && proc.unixId() !== target.pid) return false;
@@ -526,7 +535,7 @@ export class MacOSPlatform {
               closeEnough(size[1], b.height, 24);
           } catch(e) {}
 
-          try { return String(win.id()) === String("${escapedWindowId}"); } catch(e) {}
+          try { return String(win.id()) === String(${windowIdLiteral}); } catch(e) {}
           return false;
         }
 
@@ -534,7 +543,7 @@ export class MacOSPlatform {
         var foundProc = null;
 
         // Fast path: resolve "ProcessName/winN" format directly
-        var idParts = "${escapedWindowId}".split('/');
+        var idParts = ${windowIdLiteral}.split('/');
         if (idParts.length >= 2 && idParts[0]) {
           var procName = idParts[0];
           var winIdx = 0;
@@ -575,7 +584,7 @@ export class MacOSPlatform {
           var winPos = foundWin.position();
           var winSize = foundWin.size();
           result.window = {
-            id: String("${escapedWindowId}"),
+            id: String(${windowIdLiteral}),
             title: foundWin.name() || '',
             processName: foundProc.name() || '',
             pid: foundProc.unixId ? foundProc.unixId() : 0,
@@ -822,7 +831,7 @@ export class MacOSPlatform {
         }
     }
     async ocrJxa(tmpPath, screenSize, scaleFactor, region, buf) {
-        const escapedPath = tmpPath.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, "\\`").replace(/$/g, "\\$");
+        const pathLiteral = JSON.stringify(tmpPath);
         const jxaScript = `
       function run() {
         ObjC.import('Vision');
@@ -830,7 +839,7 @@ export class MacOSPlatform {
         ObjC.import('Foundation');
         var app = Application.currentApplication();
         app.includeStandardAdditions = true;
-        var path = "${escapedPath}";
+        var path = ${pathLiteral};
         var url = $.NSURL.fileURLWithPath(path);
         var image = $.NSImage.alloc.initWithContentsOfURL(url);
         if (!image || !image.isValid) {
@@ -914,10 +923,10 @@ export class MacOSPlatform {
         const effectiveApp = app || this.activeTarget?.appName;
         const maxDepth = Math.min(depth || 5, 10);
         const maxResults = Math.min(Math.max(options.maxResults ?? 50, 1), 200);
-        const escapedApp = (effectiveApp || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
-        const escapedText = text ? text.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$') : "";
-        const escapedRole = role ? role.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$') : "";
-        const escapedValue = value ? value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$') : "";
+        const appLiteral = JSON.stringify(effectiveApp || "");
+        const textLiteral = text ? JSON.stringify(text) : "null";
+        const roleLiteral = role ? JSON.stringify(role) : "null";
+        const valueLiteral = value ? JSON.stringify(value) : "null";
         // Pre-compile regex on TS side to validate syntax before passing to JXA
         if (text && textMode === "regex") {
             try {
@@ -941,11 +950,7 @@ export class MacOSPlatform {
         const startTime = Date.now();
         const jxaScript = `
         var se = Application('System Events');
-      function childElements(elem) {
-        try { return elem.uiElements(); } catch(e1) {
-          try { return elem.elements(); } catch(e2) { return []; }
-        }
-      }
+        ${jxaChildElements()}
         var results = [];
       var scannedCount = 0;
       var matchedCount = 0;
@@ -953,22 +958,13 @@ export class MacOSPlatform {
       var maxResults = ${maxResults};
       var includeBounds = ${includeBounds ? "true" : "false"};
       var visibleOnly = ${visibleOnly ? "true" : "false"};
-      var textMode = "${textMode}";
+      var textMode = ${JSON.stringify(textMode)};
 
-      var textFilter = ${text ? `"${escapedText}"` : "null"};
-      var roleFilter = ${role ? `"${escapedRole}"` : "null"};
-      var valueFilter = ${value ? `"${escapedValue}"` : "null"};
+      var textFilter = ${textLiteral};
+      var roleFilter = ${roleLiteral};
+      var valueFilter = ${valueLiteral};
 
-      function isVisible(elem) {
-        try {
-          var pos = elem.position();
-          var sz = elem.size();
-          if (!pos || !sz) return false;
-          return sz[0] > 0 && sz[1] > 0 && pos[0] > -10000 && pos[1] > -10000;
-        } catch(e) {
-          return false;
-        }
-      }
+        ${jxaIsVisible()}
 
       // Shared filter helper. textMatches and valueMatches used to be near
       // copies of the same three-branch dispatch (contains / exact / regex);
@@ -1035,15 +1031,7 @@ export class MacOSPlatform {
         return true;
       }
 
-      function getBounds(elem) {
-        try {
-          var pos = elem.position();
-          var sz = elem.size();
-          return {x: pos[0] || 0, y: pos[1] || 0, width: sz[0] || 0, height: sz[1] || 0};
-        } catch(e) {
-          return {x: 0, y: 0, width: 0, height: 0};
-        }
-      }
+        ${jxaGetBounds()}
 
       function traverse(elem, path, currentDepth) {
         if (resultCount[0] >= maxResults) return;
@@ -1094,11 +1082,11 @@ export class MacOSPlatform {
       }
 
       try {
-        if ("${escapedApp}") {
-          var proc = se.processes["${escapedApp}"]();
+        if (${appLiteral}) {
+          var proc = se.processes[${appLiteral}]();
           var wins = proc.windows();
           for (var w = 0; w < wins.length && resultCount[0] < maxResults; w++) {
-            traverse(wins[w], "${escapedApp}/win" + w, 0);
+            traverse(wins[w], ${appLiteral} + "/win" + w, 0);
           }
         } else {
           var procs = se.processes();
@@ -1183,9 +1171,9 @@ export class MacOSPlatform {
     }
     async clickElement(elementId, app) {
         this.evictExpiredCacheEntries();
-        const escapedElementId = elementId.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+        const elementIdLiteral = JSON.stringify(elementId);
         const effectiveApp = app || this.activeTarget?.appName;
-        const escapedApp = (effectiveApp || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+        const appLiteral = JSON.stringify(effectiveApp || "");
         const cached = this.elementCache.get(elementId);
         if (cached && this.isCacheEntryExpired(cached)) {
             this.elementCache.delete(elementId);
@@ -1194,173 +1182,12 @@ export class MacOSPlatform {
         const jxaScript = `
       var se = Application('System Events');
       var _result = null;
-      function childElements(elem) {
-        try { return elem.uiElements(); } catch(e1) {
-          try { return elem.elements(); } catch(e2) { return []; }
-        }
-      }
-      var elemPath = "${escapedElementId}";
-      var appName = "${escapedApp}";
+      ${jxaElementActionHelpers()}
+      var elemPath = ${elementIdLiteral};
+      var appName = ${appLiteral};
       var cached = ${cachedJson};
 
-      function resolveElementByFullPath(path) {
-        var parts = path.split('/');
-        if (parts.length < 2) return null;
-
-        var procName = parts[0];
-        var winPart = parts[1];
-        var winIdx = 0;
-        var match = winPart.match(/^win(\\\\d+)$/);
-        if (match) {
-          winIdx = parseInt(match[1]);
-        }
-
-        try {
-          var proc = se.processes[procName]();
-          var wins = proc.windows();
-          if (winIdx >= wins.length) return null;
-          var current = wins[winIdx];
-
-          for (var i = 2; i < parts.length; i++) {
-            var idx = parseInt(parts[i]);
-            if (isNaN(idx)) return null;
-            try {
-              var kids = childElements(current);
-              if (idx >= kids.length) return null;
-              current = kids[idx];
-            } catch(e) { return null; }
-          }
-          return current;
-        } catch(e) { return null; }
-      }
-
-      function elemString(elem, getter) {
-        try {
-          var value = getter(elem);
-          return value === undefined || value === null ? '' : String(value);
-        } catch(e) {
-          return '';
-        }
-      }
-
-      function getBounds(elem) {
-        try {
-          var pos = elem.position();
-          var sz = elem.size();
-          return {x: pos[0] || 0, y: pos[1] || 0, width: sz[0] || 0, height: sz[1] || 0};
-        } catch(e) {
-          return {x: 0, y: 0, width: 0, height: 0};
-        }
-      }
-
-      function descriptorMatches(elem) {
-        if (!cached) return true;
-        var role = elemString(elem, function(e) { return e.role(); });
-        var name = elemString(elem, function(e) { return e.name(); });
-        var desc = elemString(elem, function(e) { return e.description(); });
-        var value = elemString(elem, function(e) { return e.value(); });
-        if (cached.role && role && role !== cached.role) return false;
-        if (cached.name && name && name !== cached.name) return false;
-        if (cached.value && value && value !== cached.value) return false;
-        if (cached.description && desc && desc !== cached.description) return false;
-        return true;
-      }
-
-      function scoreEquivalent(elem) {
-        if (!cached) return -1;
-        var score = 0;
-        var role = elemString(elem, function(e) { return e.role(); });
-        var name = elemString(elem, function(e) { return e.name(); });
-        var desc = elemString(elem, function(e) { return e.description(); });
-        var value = elemString(elem, function(e) { return e.value(); });
-        var subrole = elemString(elem, function(e) { return e.subrole(); });
-        var identifier = elemString(elem, function(e) { return e.identifier(); });
-        if (cached.role && role === cached.role) score += 4;
-        if (cached.name && name === cached.name) score += 4;
-        if (cached.value && value === cached.value) score += 3;
-        if (cached.description && desc === cached.description) score += 2;
-        if (cached.subrole && subrole === cached.subrole) score += 2;
-        if (cached.identifier && identifier === cached.identifier) score += 3;
-        var b = getBounds(elem);
-        if (cached.bounds) {
-          var cx = b.x + b.width / 2;
-          var cy = b.y + b.height / 2;
-          var ocx = cached.bounds.x + cached.bounds.width / 2;
-          var ocy = cached.bounds.y + cached.bounds.height / 2;
-          var distance = Math.sqrt(Math.pow(cx - ocx, 2) + Math.pow(cy - ocy, 2));
-          if (distance < 8) score += 4;
-          else if (distance < 40) score += 2;
-          else if (distance < 120) score += 1;
-        }
-        return score;
-      }
-
-      function refetchEquivalent() {
-        if (!cached) return null;
-        var targetApp = appName || cached.appName || '';
-        var best = null;
-        var bestScore = 0;
-        var visited = [0];
-        function visit(elem, depth) {
-          if (visited[0] > 350 || depth > 10) return;
-          visited[0]++;
-          var score = scoreEquivalent(elem);
-          if (score > bestScore) {
-            best = elem;
-            bestScore = score;
-          }
-          try {
-            var kids = childElements(elem);
-            for (var i = 0; i < kids.length; i++) visit(kids[i], depth + 1);
-          } catch(e) {}
-        }
-        try {
-          if (targetApp) {
-            var proc = se.processes[targetApp]();
-            var wins = proc.windows();
-            for (var w = 0; w < wins.length; w++) visit(wins[w], 0);
-          } else {
-            var procs = se.processes();
-            for (var p = 0; p < procs.length; p++) {
-              try {
-                var wins2 = procs[p].windows();
-                for (var w2 = 0; w2 < wins2.length; w2++) visit(wins2[w2], 0);
-              } catch(e2) {}
-            }
-          }
-        } catch(e) {}
-        return bestScore >= 6 ? best : null;
-      }
-
-      var elem = null;
-
-      if (appName) {
-        try {
-          var proc = se.processes[appName]();
-          var wins = proc.windows();
-          var parts = elemPath.split('/');
-          var winIdx = 0;
-          var match = parts[0].match(/^win(\\\\d+)$/);
-          if (match) winIdx = parseInt(match[1]);
-          if (winIdx < wins.length) {
-            var current = wins[winIdx];
-            for (var i = 1; i < parts.length; i++) {
-              var idx = parseInt(parts[i]);
-              if (isNaN(idx)) break;
-              try {
-                var kids = childElements(current);
-                if (idx >= kids.length) break;
-                current = kids[idx];
-              } catch(e) { break; }
-            }
-            elem = current;
-          }
-        } catch(e) {}
-      }
-
-      if (!elem) {
-        elem = resolveElementByFullPath(elemPath);
-      }
+      var elem = resolveElementInApp(elemPath, appName) || resolveElementByFullPath(elemPath);
 
       if (elem && !descriptorMatches(elem)) {
         elem = refetchEquivalent() || elem;
@@ -1415,10 +1242,10 @@ export class MacOSPlatform {
     }
     async typeInElement(elementId, text, app, clearFirst) {
         this.evictExpiredCacheEntries();
-        const escapedText = text.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+        const textLiteral = JSON.stringify(text);
         const effectiveApp = app || this.activeTarget?.appName;
-        const escapedApp = (effectiveApp || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
-        const escapedElementId = elementId.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/`/g, '\\`').replace(/\$/g, '\\$');
+        const appLiteral = JSON.stringify(effectiveApp || "");
+        const elementIdLiteral = JSON.stringify(elementId);
         const cached = this.elementCache.get(elementId);
         if (cached && this.isCacheEntryExpired(cached)) {
             this.elementCache.delete(elementId);
@@ -1427,175 +1254,14 @@ export class MacOSPlatform {
         const jxaScript = `
       var se = Application('System Events');
       var _result = null;
-      function childElements(elem) {
-        try { return elem.uiElements(); } catch(e1) {
-          try { return elem.elements(); } catch(e2) { return []; }
-        }
-      }
-      var elemPath = "${escapedElementId}";
-      var appName = "${escapedApp}";
-      var textToType = "${escapedText}";
+      ${jxaElementActionHelpers()}
+      var elemPath = ${elementIdLiteral};
+      var appName = ${appLiteral};
+      var textToType = ${textLiteral};
       var shouldClear = ${clearFirst ? "true" : "false"};
       var cached = ${cachedJson};
 
-      function resolveElementByFullPath(path) {
-        var parts = path.split('/');
-        if (parts.length < 2) return null;
-
-        var procName = parts[0];
-        var winPart = parts[1];
-        var winIdx = 0;
-        var match = winPart.match(/^win(\\\\d+)$/);
-        if (match) {
-          winIdx = parseInt(match[1]);
-        }
-
-        try {
-          var proc = se.processes[procName]();
-          var wins = proc.windows();
-          if (winIdx >= wins.length) return null;
-          var current = wins[winIdx];
-
-          for (var i = 2; i < parts.length; i++) {
-            var idx = parseInt(parts[i]);
-            if (isNaN(idx)) return null;
-            try {
-              var kids = childElements(current);
-              if (idx >= kids.length) return null;
-              current = kids[idx];
-            } catch(e) { return null; }
-          }
-          return current;
-        } catch(e) { return null; }
-      }
-
-      function elemString(elem, getter) {
-        try {
-          var value = getter(elem);
-          return value === undefined || value === null ? '' : String(value);
-        } catch(e) {
-          return '';
-        }
-      }
-
-      function getBounds(elem) {
-        try {
-          var pos = elem.position();
-          var sz = elem.size();
-          return {x: pos[0] || 0, y: pos[1] || 0, width: sz[0] || 0, height: sz[1] || 0};
-        } catch(e) {
-          return {x: 0, y: 0, width: 0, height: 0};
-        }
-      }
-
-      function descriptorMatches(elem) {
-        if (!cached) return true;
-        var role = elemString(elem, function(e) { return e.role(); });
-        var name = elemString(elem, function(e) { return e.name(); });
-        var desc = elemString(elem, function(e) { return e.description(); });
-        var value = elemString(elem, function(e) { return e.value(); });
-        if (cached.role && role && role !== cached.role) return false;
-        if (cached.name && name && name !== cached.name) return false;
-        if (cached.value && value && value !== cached.value) return false;
-        if (cached.description && desc && desc !== cached.description) return false;
-        return true;
-      }
-
-      function scoreEquivalent(elem) {
-        if (!cached) return -1;
-        var score = 0;
-        var role = elemString(elem, function(e) { return e.role(); });
-        var name = elemString(elem, function(e) { return e.name(); });
-        var desc = elemString(elem, function(e) { return e.description(); });
-        var value = elemString(elem, function(e) { return e.value(); });
-        var subrole = elemString(elem, function(e) { return e.subrole(); });
-        var identifier = elemString(elem, function(e) { return e.identifier(); });
-        if (cached.role && role === cached.role) score += 4;
-        if (cached.name && name === cached.name) score += 4;
-        if (cached.value && value === cached.value) score += 3;
-        if (cached.description && desc === cached.description) score += 2;
-        if (cached.subrole && subrole === cached.subrole) score += 2;
-        if (cached.identifier && identifier === cached.identifier) score += 3;
-        var b = getBounds(elem);
-        if (cached.bounds) {
-          var cx = b.x + b.width / 2;
-          var cy = b.y + b.height / 2;
-          var ocx = cached.bounds.x + cached.bounds.width / 2;
-          var ocy = cached.bounds.y + cached.bounds.height / 2;
-          var distance = Math.sqrt(Math.pow(cx - ocx, 2) + Math.pow(cy - ocy, 2));
-          if (distance < 8) score += 4;
-          else if (distance < 40) score += 2;
-          else if (distance < 120) score += 1;
-        }
-        return score;
-      }
-
-      function refetchEquivalent() {
-        if (!cached) return null;
-        var targetApp = appName || cached.appName || '';
-        var best = null;
-        var bestScore = 0;
-        var visited = [0];
-        function visit(elem, depth) {
-          if (visited[0] > 350 || depth > 10) return;
-          visited[0]++;
-          var score = scoreEquivalent(elem);
-          if (score > bestScore) {
-            best = elem;
-            bestScore = score;
-          }
-          try {
-            var kids = childElements(elem);
-            for (var i = 0; i < kids.length; i++) visit(kids[i], depth + 1);
-          } catch(e) {}
-        }
-        try {
-          if (targetApp) {
-            var proc = se.processes[targetApp]();
-            var wins = proc.windows();
-            for (var w = 0; w < wins.length; w++) visit(wins[w], 0);
-          } else {
-            var procs = se.processes();
-            for (var p = 0; p < procs.length; p++) {
-              try {
-                var wins2 = procs[p].windows();
-                for (var w2 = 0; w2 < wins2.length; w2++) visit(wins2[w2], 0);
-              } catch(e2) {}
-            }
-          }
-        } catch(e) {}
-        return bestScore >= 6 ? best : null;
-      }
-
-      var elem = null;
-
-      if (appName) {
-        try {
-          var proc = se.processes[appName]();
-          var wins = proc.windows();
-          var parts = elemPath.split('/');
-          var winIdx = 0;
-          var match = parts[0].match(/^win(\\\\d+)$/);
-          if (match) winIdx = parseInt(match[1]);
-          if (winIdx < wins.length) {
-            var current = wins[winIdx];
-            for (var i = 1; i < parts.length; i++) {
-              var idx = parseInt(parts[i]);
-              if (isNaN(idx)) break;
-              try {
-                var kids = childElements(current);
-                if (idx >= kids.length) break;
-                current = kids[idx];
-              } catch(e) { break; }
-            }
-            elem = current;
-          }
-        } catch(e) {}
-      }
-
-      if (!elem) {
-        elem = resolveElementByFullPath(elemPath);
-      }
+      var elem = resolveElementInApp(elemPath, appName) || resolveElementByFullPath(elemPath);
 
       if (elem && !descriptorMatches(elem)) {
         elem = refetchEquivalent() || elem;
@@ -1691,170 +1357,12 @@ export class MacOSPlatform {
         const jxaScript = `
       var se = Application('System Events');
       var _result = null;
-      function childElements(elem) {
-        try { return elem.uiElements(); } catch(e1) {
-          try { return elem.elements(); } catch(e2) { return []; }
-        }
-      }
+      ${jxaElementActionHelpers()}
       var elemPath = ${elementIdLiteral};
       var appName = ${appLiteral};
       var valueToSet = ${valueLiteral};
       var cached = ${cachedJson};
 
-      function resolveElementByFullPath(path) {
-        var parts = path.split('/');
-        if (parts.length < 2) return null;
-
-        var procName = parts[0];
-        var winPart = parts[1];
-        var winIdx = 0;
-        var match = winPart.match(/^win(\\\\d+)$/);
-        if (match) winIdx = parseInt(match[1]);
-
-        try {
-          var proc = se.processes[procName]();
-          var wins = proc.windows();
-          if (winIdx >= wins.length) return null;
-          var current = wins[winIdx];
-
-          for (var i = 2; i < parts.length; i++) {
-            var idx = parseInt(parts[i]);
-            if (isNaN(idx)) return null;
-            try {
-              var kids = childElements(current);
-              if (idx >= kids.length) return null;
-              current = kids[idx];
-            } catch(e) { return null; }
-          }
-          return current;
-        } catch(e) { return null; }
-      }
-
-      function resolveElementInApp(path, targetApp) {
-        if (!targetApp) return null;
-        var parts = path.split('/');
-        var start = parts[0] === targetApp ? 1 : 0;
-        var winPart = parts[start] || 'win0';
-        var winIdx = 0;
-        var match = winPart.match(/^win(\\\\d+)$/);
-        if (match) winIdx = parseInt(match[1]);
-
-        try {
-          var proc = se.processes[targetApp]();
-          var wins = proc.windows();
-          if (winIdx >= wins.length) return null;
-          var current = wins[winIdx];
-          for (var i = start + 1; i < parts.length; i++) {
-            var idx = parseInt(parts[i]);
-            if (isNaN(idx)) return null;
-            try {
-              var kids = childElements(current);
-              if (idx >= kids.length) return null;
-              current = kids[idx];
-            } catch(e) { return null; }
-          }
-          return current;
-        } catch(e) { return null; }
-      }
-
-      function elemString(elem, getter) {
-        try {
-          var value = getter(elem);
-          return value === undefined || value === null ? '' : String(value);
-        } catch(e) {
-          return '';
-        }
-      }
-
-      function getBounds(elem) {
-        try {
-          var pos = elem.position();
-          var sz = elem.size();
-          return {x: pos[0] || 0, y: pos[1] || 0, width: sz[0] || 0, height: sz[1] || 0};
-        } catch(e) {
-          return {x: 0, y: 0, width: 0, height: 0};
-        }
-      }
-
-      function descriptorMatches(elem) {
-        if (!cached) return true;
-        var role = elemString(elem, function(e) { return e.role(); });
-        var name = elemString(elem, function(e) { return e.name(); });
-        var desc = elemString(elem, function(e) { return e.description(); });
-        var value = elemString(elem, function(e) { return e.value(); });
-        if (cached.role && role && role !== cached.role) return false;
-        if (cached.name && name && name !== cached.name) return false;
-        if (cached.value && value && value !== cached.value) return false;
-        if (cached.description && desc && desc !== cached.description) return false;
-        return true;
-      }
-
-      function scoreEquivalent(elem) {
-        if (!cached) return -1;
-        var score = 0;
-        var role = elemString(elem, function(e) { return e.role(); });
-        var name = elemString(elem, function(e) { return e.name(); });
-        var desc = elemString(elem, function(e) { return e.description(); });
-        var value = elemString(elem, function(e) { return e.value(); });
-        var subrole = elemString(elem, function(e) { return e.subrole(); });
-        var identifier = elemString(elem, function(e) { return e.identifier(); });
-        if (cached.role && role === cached.role) score += 4;
-        if (cached.name && name === cached.name) score += 4;
-        if (cached.value && value === cached.value) score += 3;
-        if (cached.description && desc === cached.description) score += 2;
-        if (cached.subrole && subrole === cached.subrole) score += 2;
-        if (cached.identifier && identifier === cached.identifier) score += 3;
-        var b = getBounds(elem);
-        if (cached.bounds) {
-          var cx = b.x + b.width / 2;
-          var cy = b.y + b.height / 2;
-          var ocx = cached.bounds.x + cached.bounds.width / 2;
-          var ocy = cached.bounds.y + cached.bounds.height / 2;
-          var distance = Math.sqrt(Math.pow(cx - ocx, 2) + Math.pow(cy - ocy, 2));
-          if (distance < 8) score += 4;
-          else if (distance < 40) score += 2;
-          else if (distance < 120) score += 1;
-        }
-        return score;
-      }
-
-      function refetchEquivalent() {
-        if (!cached) return null;
-        var targetApp = appName || cached.appName || '';
-        var best = null;
-        var bestScore = 0;
-        var visited = [0];
-        function visit(elem, depth) {
-          if (visited[0] > 350 || depth > 10) return;
-          visited[0]++;
-          var score = scoreEquivalent(elem);
-          if (score > bestScore) {
-            best = elem;
-            bestScore = score;
-          }
-          try {
-            var kids = childElements(elem);
-            for (var i = 0; i < kids.length; i++) visit(kids[i], depth + 1);
-          } catch(e) {}
-        }
-        try {
-          if (targetApp) {
-            var proc = se.processes[targetApp]();
-            var wins = proc.windows();
-            for (var w = 0; w < wins.length; w++) visit(wins[w], 0);
-          } else {
-            var procs = se.processes();
-            for (var p = 0; p < procs.length; p++) {
-              try {
-                var wins2 = procs[p].windows();
-                for (var w2 = 0; w2 < wins2.length; w2++) visit(wins2[w2], 0);
-              } catch(e2) {}
-            }
-          }
-        } catch(e) {}
-        return bestScore >= 6 ? best : null;
-      }
-
       var elem = resolveElementInApp(elemPath, appName) || resolveElementByFullPath(elemPath);
       if (elem && !descriptorMatches(elem)) {
         elem = refetchEquivalent() || elem;