ucu-mcp 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-06-16
+
+方向4b AXPress verify-then-fallback + 方向5 FocusStealSuppression @deprecated 文档化。
+
+### Added
+
+- **方向4b AXPress verify-then-fallback（clickElement + clickMenuBarExtra）**：解决 Tauri/Electron 控件静默吞 AXPress（不抛异常也不执行）。双层策略：(1) 启发式跳过——对已知静默吞的应用（`AX_SILENT_APP_HINTS = ["tauri"]`，按 appName includes 匹配）直接坐标点击，跳过 AXPress；(2) verify 状态签名——对走 AXPress 的应用，采样前后 `value|focused|selected` 签名，spin 80ms 等异步生效，无变化则降级坐标。`ClickResult { method: "axpress"|"coordinate"; verified: boolean }` 透到 ActionReceipt.result，verified:false 时附 warning 引导模型用 screenshot/get_window_state 复核。无可观测状态的元素（纯按钮）保守判 verified:false 但不降级坐标（避免误伤）。共享 JXA 原语 `stateSignature`/`coordinateClick`/`spinMs`。
+- 返回类型波及链：`clickElement`/`clickMenuBarExtra` `Promise<void>` → `Promise<ClickResult>`（base.ts 接口 + windows/linux stub + element.ts consumer + tools-layer mock）。
+
+### Changed
+
+- **方向5 FocusStealSuppression @deprecated 文档化**：`focus.ts` 的 `saveFocus`/`restoreFocus` 加 `@deprecated` JSDoc，说明 CGEvent 在 HID 层工作不需前台 focus、焦点管理被有意禁用、`tools-layer.test.ts` 的 `not.toHaveBeenCalled()` 锁定禁用态。不删不接线（文档化设计决策，非遗漏）。`base.ts` 接口注释同步。
+
+### Fixed
+
+- 无行为修复（4b/5 是 v0.5.0 的质量强化）。
+
+### 真机验证（2026-06-16）
+
+- ✅ doctor 全绿（3 native helpers + 权限 + 26 工具）。
+- ✅ OCR（方向1）返回非空 elements，无 NSNull 崩溃。
+- ✅ press_key 字母键 Cmd+M（方向2）成功合成，不报 Unknown key。
+- ✅ describe_screen（方向3）结构正确，AX 失败时聚合到 errors[] 不抛出。
+- ✅ focus_app(cc-switch)（方向4a）建立 tray target（windowId:"tray"），不抛 WINDOW_NOT_FOUND。
+- ✅ click_menu_bar_extra（方向4b）返回 `method:"axpress", verified:true`——托盘菜单真实打开（OCR 确认 "About/Hide/Quit CC Switch" 菜单项可见）。
+- ⚠️ 发现：cc-switch 托盘菜单是其**原生应用菜单**（About/Hide/Quit），"使用统计"在 WebView 设置面板内，不在托盘菜单。完整 "设置→使用统计" 流程需先打开设置窗口（非托盘菜单可达），留 follow-up。
+
+### Tests
+
+- 303→310（+7：clickElement ClickResult 解析、JXA stateSignature/spinMs/coordinateClick/sigBefore/sigAfter/preferCoord source 断言、Tauri 启发式 preferCoord=true、tools-layer method/verified 透出 + warnings）。
+
 ## [0.5.0] - 2026-06-15
 
 cc-switch 操控诊断与视觉通道修复：打通 OCR + 字母快捷键 + 托盘 + 视觉降级 fallback + 内置 agent skill。

package/dist/src/mcp/tools/element-tools.js

@@ -36,8 +36,13 @@ export function registerElementTools(registerTool) {
     }, async (params) => {
         const effectiveApp = params.app || getActiveTarget()?.appName;
         const safetyCtx = await getSafetyContext();
-        await withSafety({ action: "click_element", params: { ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().clickElement(params.elementId, effectiveApp) });
-        return actionResponse("click_element", { clicked: true, elementId: params.elementId }, { elementId: params.elementId, app: effectiveApp }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const clickResult = await withSafety({ action: "click_element", params: { ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().clickElement(params.elementId, effectiveApp) });
+        const warnings = clickResult.verified
+            ? []
+            : [clickResult.method === "coordinate"
+                    ? "AXPress produced no observable state change (or the app is known to silently swallow it); coordinate fallback was used. Re-observe with screenshot/get_window_state to confirm."
+                    : "AXPress completed but the element exposed no observable state to verify against. Re-observe with screenshot/get_window_state to confirm."];
+        return actionResponse("click_element", { clicked: true, elementId: params.elementId, method: clickResult.method, verified: clickResult.verified }, { elementId: params.elementId, app: effectiveApp }, params.captureAfter, params.captureFormat, params.captureMaxWidth, warnings);
     });
     registerTool("set_value", "Set the value of an accessibility element", {
         elementId: z.string().describe("AX element identifier"), value: z.string().describe("Value to set"), app: z.string().optional().describe("Target app"), ...captureAfterFields,
@@ -64,7 +69,12 @@ export function registerElementTools(registerTool) {
         ...captureAfterFields,
     }, async (params) => {
         const safetyCtx = await getSafetyContext();
-        await withSafety({ action: "click_menu_bar_extra", params: { ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().clickMenuBarExtra(params.app, { description: params.description, name: params.name, index: params.index }) });
-        return actionResponse("click_menu_bar_extra", { clicked: true, app: params.app }, { app: params.app }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const clickResult = await withSafety({ action: "click_menu_bar_extra", params: { ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().clickMenuBarExtra(params.app, { description: params.description, name: params.name, index: params.index }) });
+        const warnings = clickResult.verified
+            ? []
+            : [clickResult.method === "coordinate"
+                    ? "AXPress produced no observable state change; coordinate fallback was used. Use find_element or screenshot to confirm the menu opened."
+                    : "AXPress completed but the status item exposed no observable state to verify against. Use find_element or screenshot to confirm the menu opened."];
+        return actionResponse("click_menu_bar_extra", { clicked: true, app: params.app, method: clickResult.method, verified: clickResult.verified }, { app: params.app }, params.captureAfter, params.captureFormat, params.captureMaxWidth, warnings);
     });
 }

package/dist/src/platform/base.d.ts

@@ -126,6 +126,17 @@ export interface WindowState {
     focusedElement?: ElementInfo;
     tree?: ElementInfo;
 }
+/**
+ * Outcome of an AX-driven click — surfaces whether AXPress was used and whether
+ * its effect was observable. `verified:false` means either the element exposed
+ * no observable state (inconclusive) or the click fell back to coordinates
+ * (silent AXPress swallow on Tauri/Electron). The tool layer surfaces this so
+ * the model can decide whether to re-observe via screenshot/get_window_state.
+ */
+export interface ClickResult {
+    method: "axpress" | "coordinate";
+    verified: boolean;
+}
 /**
  * Structured text description of the screen — a fallback for environments where
  * image content blocks are downgraded to URLs (so the model cannot see screenshots).
@@ -169,7 +180,7 @@ export interface Platform {
     type(text: string, delay?: number): Promise<void>;
     key(keys: string[]): Promise<void>;
     findElement(options: FindElementOptions): Promise<FindElementResponse>;
-    clickElement(elementId: string, app?: string): Promise<void>;
+    clickElement(elementId: string, app?: string): Promise<ClickResult>;
     typeInElement(elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;
     setElementValue?(elementId: string, value: string, app?: string): Promise<void>;
     findMenuBarExtra?(app: string): Promise<unknown[]>;
@@ -177,7 +188,7 @@ export interface Platform {
         description?: string;
         name?: string;
         index?: number;
-    }): Promise<void>;
+    }): Promise<ClickResult>;
     isScreenLocked?(): boolean;
     saveFocus?(): Promise<void>;
     restoreFocus?(): Promise<void>;

package/dist/src/platform/linux.d.ts

@@ -1,4 +1,4 @@
-import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse } from "./base.js";
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse, ClickResult } from "./base.js";
 /**
  * Linux platform adapter (AT-SPI2 + xdotool fallback)
  * TODO: Implement with D-Bus AT-SPI2 bindings
@@ -17,7 +17,7 @@ export declare class LinuxPlatform implements Platform {
     key(keys: string[]): Promise<void>;
     ocr(_display?: number, _region?: ScreenRegion): Promise<OcrResult>;
     findElement(_options: FindElementOptions): Promise<FindElementResponse>;
-    clickElement(_elementId: string, _app?: string): Promise<void>;
+    clickElement(_elementId: string, _app?: string): Promise<ClickResult>;
     typeInElement(_elementId: string, _text: string, _app?: string, _clearFirst?: boolean): Promise<void>;
     readClipboard(): Promise<string>;
     writeClipboard(text: string): Promise<void>;

package/dist/src/platform/macos/element.d.ts

@@ -1,5 +1,6 @@
 import type { MacOSPlatform } from "./base.js";
-export declare function clickElement(this: MacOSPlatform, elementId: string, app?: string): Promise<void>;
+import type { ClickResult } from "../base.js";
+export declare function clickElement(this: MacOSPlatform, elementId: string, app?: string): Promise<ClickResult>;
 export declare function typeInElement(this: MacOSPlatform, elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;
 export declare function setElementValue(this: MacOSPlatform, elementId: string, value: string, app?: string): Promise<void>;
 export interface MenuBarExtraItem {
@@ -21,4 +22,4 @@ export interface MenuBarExtraSelector {
 }
 export declare function findMenuBarExtra(this: MacOSPlatform, app: string): Promise<MenuBarExtraItem[]>;
 export declare function matchMenuBarExtra(items: MenuBarExtraItem[], selector: MenuBarExtraSelector): MenuBarExtraItem | undefined;
-export declare function clickMenuBarExtra(this: MacOSPlatform, app: string, selector?: MenuBarExtraSelector): Promise<void>;
+export declare function clickMenuBarExtra(this: MacOSPlatform, app: string, selector?: MenuBarExtraSelector): Promise<ClickResult>;

package/dist/src/platform/macos/element.js

@@ -2,6 +2,20 @@ import { execFileSync } from "node:child_process";
 import { ElementNotFoundError } from "../../util/errors.js";
 import { rethrowElementActionError } from "./helpers.js";
 import { jxaElementActionHelpers } from "../jxa-helpers.js";
+/**
+ * App-name hints for which AXPress is known to be silently swallowed
+ * (Tauri custom window decorations, some Electron controls). When the target
+ * app matches, clickElement/clickMenuBarExtra skip AXPress and go straight to
+ * a coordinate click. Conservative starting set — extend as more silent-swallow
+ * apps are confirmed.
+ */
+const AX_SILENT_APP_HINTS = ["tauri"];
+function preferCoordinateClick(appName) {
+    if (!appName)
+        return false;
+    const n = appName.toLowerCase();
+    return AX_SILENT_APP_HINTS.some((h) => n.includes(h));
+}
 function prepareCache(elementId) {
     this.evictExpiredCacheEntries();
     const cached = this.elementCache.get(elementId);
@@ -10,22 +24,65 @@ function prepareCache(elementId) {
     }
     return this.elementCache.get(elementId) ?? null;
 }
+/**
+ * Shared JXA snippet: read an observable state signature from an AX element.
+ * Used by clickElement/clickMenuBarExtra to verify whether AXPress actually
+ * changed anything (Tauri/Electron silently swallow AXPress without throwing).
+ * Returns a string concatenation of value/focused/selected (each defensively
+ * read; missing attributes contribute ''). An empty signature means the element
+ * exposes no observable state — verification is inconclusive.
+ */
+const JXA_STATE_SIGNATURE = `
+  function stateSignature(elem) {
+    var parts = [];
+    try { var v = elem.value(); parts.push('v=' + (v === undefined || v === null ? '' : String(v))); } catch(e) { parts.push('v='); }
+    try { parts.push('f=' + (elem.focused ? (elem.focused() ? 1 : 0) : '')); } catch(e) { parts.push('f='); }
+    try { parts.push('s=' + (elem.selected ? (elem.selected() ? 1 : 0) : '')); } catch(e) { parts.push('s='); }
+    return parts.join('|');
+  }
+  // Brief synchronous spin to let an async AXPress propagate state.
+  function spinMs(ms) { var t = Date.now(); while (Date.now() - t < ms) {} }
+`;
+/**
+ * Shared JXA snippet: perform a coordinate click at the element's bounds center.
+ * Returns the {x, y} used, or null if bounds could not be read.
+ */
+const JXA_COORDINATE_CLICK = `
+  function coordinateClick(elem) {
+    var pos = elem.position();
+    var sz = elem.size();
+    var cx = pos[0] + sz[0] / 2;
+    var cy = pos[1] + sz[1] / 2;
+    ObjC.import('CoreGraphics');
+    var src = $.CGEventSourceCreate($.kCGEventSourceStateHIDSystemState);
+    var pt = $.CGPointMake(cx, cy);
+    var down = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
+    $.CGEventPost($.kCGHIDEventTap, down);
+    var up = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
+    $.CGEventPost($.kCGHIDEventTap, up);
+    return {x: cx, y: cy};
+  }
+`;
 export async function clickElement(elementId, app) {
     const elementIdLiteral = JSON.stringify(elementId);
     const effectiveApp = app || this.activeTarget?.appName;
     const appLiteral = JSON.stringify(effectiveApp || "");
     const cachedDescriptor = prepareCache.call(this, elementId);
     const cachedJson = JSON.stringify(cachedDescriptor);
+    const preferCoord = preferCoordinateClick(effectiveApp);
     const jxaScript = `
     var se = Application('System Events');
     var _result = null;
     ${jxaElementActionHelpers()}
+    ${JXA_STATE_SIGNATURE}
+    ${JXA_COORDINATE_CLICK}
     var elemPath = ${elementIdLiteral};
     var appName = ${appLiteral};
     // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
     var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
     var appNorm = _norm(appName);
     var cached = ${cachedJson};
+    var preferCoord = ${preferCoord ? "true" : "false"};
 
     var elem = resolveElementInApp(elemPath, appName) || resolveElementByFullPath(elemPath);
     if (elem && !descriptorMatches(elem)) {
@@ -37,27 +94,51 @@ export async function clickElement(elementId, app) {
 
     if (!elem) {
       _result = {success: false, error: "Element not found: " + elemPath};
+    } else if (preferCoord) {
+      // 启发式命中（Tauri 等已知静默吞 AXPress 的应用）：直接坐标点击
+      try {
+        coordinateClick(elem);
+        _result = {success: true, method: "coordinate", verified: false};
+      } catch(e) {
+        _result = {success: false, error: "Could not click element (coordinate): " + String(e.message || e)};
+      }
     } else {
+      // AXPress + verify：采样前后状态签名，无变化则降级坐标
+      var sigBefore = stateSignature(elem);
+      var axpressThrew = false;
       try {
         elem.actions.AXPress.perform();
-        _result = {success: true};
       } catch(e) {
+        axpressThrew = true;
+      }
+      if (axpressThrew) {
+        // AXPress 抛异常 → 坐标 fallback
         try {
-          var pos = elem.position();
-          var sz = elem.size();
-          var cx = pos[0] + sz[0] / 2;
-          var cy = pos[1] + sz[1] / 2;
-          ObjC.import('CoreGraphics');
-          var src = $.CGEventSourceCreate($.kCGEventSourceStateHIDSystemState);
-          var pt = $.CGPointMake(cx, cy);
-          var down = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
-          $.CGEventPost($.kCGHIDEventTap, down);
-          var up = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
-          $.CGEventPost($.kCGHIDEventTap, up);
-          _result = {success: true};
+          coordinateClick(elem);
+          _result = {success: true, method: "coordinate", verified: false};
         } catch(e2) {
           _result = {success: false, error: "Could not click element: " + String(e2.message || e2)};
         }
+      } else {
+        // AXPress 未抛异常：spin 等待异步生效，再采样签名判断是否真的生效
+        spinMs(80);
+        var sigAfter = stateSignature(elem);
+        if (sigBefore !== '' && sigAfter !== sigBefore) {
+          // 状态变化 → AXPress 生效
+          _result = {success: true, method: "axpress", verified: true};
+        } else if (sigBefore === '' && sigAfter === '') {
+          // 无可观测状态（纯按钮无 value/focused/selected）：无法 verify，
+          // 保守认为 AXPress 可能成功（不降级坐标，避免对正常按钮误伤）
+          _result = {success: true, method: "axpress", verified: false};
+        } else {
+          // 有可观测状态但无变化 → 静默吞，降级坐标
+          try {
+            coordinateClick(elem);
+            _result = {success: true, method: "coordinate", verified: false};
+          } catch(e3) {
+            _result = {success: false, error: "Could not click element (coordinate fallback): " + String(e3.message || e3)};
+          }
+        }
       }
     }
     JSON.stringify(_result);
@@ -73,9 +154,14 @@ export async function clickElement(elementId, app) {
                 ? new Error(result.error)
                 : new ElementNotFoundError(elementId);
         }
+        return {
+            method: result.method ?? "axpress",
+            verified: Boolean(result.verified),
+        };
     }
     catch (error) {
         rethrowElementActionError(error, "click_element", elementId);
+        return { method: "axpress", verified: false }; // unreachable — rethrow throws
     }
 }
 export async function typeInElement(elementId, text, app, clearFirst) {
@@ -372,7 +458,8 @@ export async function clickMenuBarExtra(app, selector = {}) {
     const host = target.host;
     const tgtNameLiteral = JSON.stringify(target.name || "");
     const tgtDescLiteral = JSON.stringify(target.description || "");
-    // AXPress，失败则坐标点击中心（与 clickElement 同模式，应对 Tauri 等静默吞）
+    const preferCoord = preferCoordinateClick(app);
+    // AXPress + verify-then-fallback（与 clickElement 同模式，应对 Tauri 等静默吞）。
     // host==="systemuiserver" 时在 SystemUIServer 进程上重定位（托盘 status item 由它托管），
     // SystemUIServer.menuBarItems 顺序不稳定，用保存的 name/description 二次匹配定位具体 item。
     // host==="self" 时按 app 进程的 menuBars()[mb].menuBarItems()[idx] 重定位（稳定）。
@@ -411,11 +498,14 @@ export async function clickMenuBarExtra(app, selector = {}) {
     var appName = ${appLiteral};
     var tgtName = ${tgtNameLiteral};
     var tgtDesc = ${tgtDescLiteral};
+    ${JXA_STATE_SIGNATURE}
+    ${JXA_COORDINATE_CLICK}
     // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
     var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
     var appNorm = _norm(appName);
     var tgtNameNorm = _norm(tgtName);
     var tgtDescNorm = _norm(tgtDesc);
+    var preferCoord = ${preferCoord ? "true" : "false"};
     var _matchApp = function(itemNorm) {
       if (!itemNorm) return false;
       return itemNorm === appNorm || itemNorm.indexOf(appNorm) !== -1 || appNorm.indexOf(itemNorm) !== -1;
@@ -430,21 +520,36 @@ export async function clickMenuBarExtra(app, selector = {}) {
       }
       ${resolveItemBlock}
       if (!_result && item) {
-        try {
-          item.actions.AXPress.perform();
-          _result = {success: true, method: "axpress"};
-        } catch(e) {
-          var pos = item.position();
-          var sz = item.size();
-          var cx = pos[0] + sz[0] / 2;
-          var cy = pos[1] + sz[1] / 2;
-          ObjC.import('CoreGraphics');
-          var pt = $.CGPointMake(cx, cy);
-          var down = $.CGEventCreateMouseEvent(null, $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
-          $.CGEventPost($.kCGHIDEventTap, down);
-          var up = $.CGEventCreateMouseEvent(null, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
-          $.CGEventPost($.kCGHIDEventTap, up);
-          _result = {success: true, method: "coordinate", x: cx, y: cy};
+        if (preferCoord) {
+          // 启发式命中：直接坐标点击
+          coordinateClick(item);
+          _result = {success: true, method: "coordinate", verified: false};
+        } else {
+          // AXPress + verify
+          var sigBefore = stateSignature(item);
+          var axpressThrew = false;
+          try {
+            item.actions.AXPress.perform();
+          } catch(e) {
+            axpressThrew = true;
+          }
+          if (axpressThrew) {
+            coordinateClick(item);
+            _result = {success: true, method: "coordinate", verified: false};
+          } else {
+            spinMs(80);
+            var sigAfter = stateSignature(item);
+            if (sigBefore !== '' && sigAfter !== sigBefore) {
+              _result = {success: true, method: "axpress", verified: true};
+            } else if (sigBefore === '' && sigAfter === '') {
+              // 托盘 status item 通常无可观测状态（无 value/selected）；AXPress 开菜单的效果
+              // 难以从 item 本身验证。保守认为成功（菜单是否打开由后续 find_element 判断）。
+              _result = {success: true, method: "axpress", verified: false};
+            } else {
+              coordinateClick(item);
+              _result = {success: true, method: "coordinate", verified: false};
+            }
+          }
         }
       }
     } catch(e) {
@@ -458,10 +563,14 @@ export async function clickMenuBarExtra(app, selector = {}) {
     }
     catch (error) {
         rethrowElementActionError(error, "click_menu_bar_extra", app);
-        return; // unreachable
+        return { method: "axpress", verified: false }; // unreachable — rethrow throws
     }
     const result = JSON.parse(out);
     if (!result.success) {
         throw new Error(`click_menu_bar_extra failed in ${app}: ${result.error}`);
     }
+    return {
+        method: result.method ?? "axpress",
+        verified: Boolean(result.verified),
+    };
 }

package/dist/src/platform/macos/focus.d.ts

@@ -1,3 +1,13 @@
 import type { MacOSPlatform } from "./base.js";
+/**
+ * @deprecated Focus management is intentionally disabled. CGEvent input
+ * synthesis (click/type/key) works at the HID layer and does not require the
+ * target app to be frontmost, so stealing/restoring focus is unnecessary and
+ * could disrupt the user. `saveFocus`/`restoreFocus` are retained for API
+ * compatibility but are NOT called from the action pipeline — see the
+ * `not.toHaveBeenCalled()` assertions in `tools-layer.test.ts` that lock this
+ * disabled state. Do not wire these into new code; prefer CGEvent-based input.
+ */
 export declare function saveFocus(this: MacOSPlatform): Promise<void>;
+/** @deprecated See {@link saveFocus} — intentionally disabled, not called from the action pipeline. */
 export declare function restoreFocus(this: MacOSPlatform): Promise<void>;

package/dist/src/platform/macos/focus.js

@@ -1,4 +1,13 @@
 import { execFileSync } from "node:child_process";
+/**
+ * @deprecated Focus management is intentionally disabled. CGEvent input
+ * synthesis (click/type/key) works at the HID layer and does not require the
+ * target app to be frontmost, so stealing/restoring focus is unnecessary and
+ * could disrupt the user. `saveFocus`/`restoreFocus` are retained for API
+ * compatibility but are NOT called from the action pipeline — see the
+ * `not.toHaveBeenCalled()` assertions in `tools-layer.test.ts` that lock this
+ * disabled state. Do not wire these into new code; prefer CGEvent-based input.
+ */
 export async function saveFocus() {
     try {
         const apps = await this.listApps();
@@ -16,6 +25,7 @@ export async function saveFocus() {
         this.savedFocus = undefined;
     }
 }
+/** @deprecated See {@link saveFocus} — intentionally disabled, not called from the action pipeline. */
 export async function restoreFocus() {
     if (!this.savedFocus)
         return;

package/dist/src/platform/windows.d.ts

@@ -1,4 +1,4 @@
-import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse } from "./base.js";
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse, ClickResult } from "./base.js";
 export declare class WindowsPlatform implements Platform {
     screenshot(_display?: number, _region?: ScreenRegion): Promise<Buffer>;
     getScreenSize(_display?: number): ScreenSize;
@@ -13,7 +13,7 @@ export declare class WindowsPlatform implements Platform {
     key(_keys: string[]): Promise<void>;
     ocr(_display?: number, _region?: ScreenRegion): Promise<OcrResult>;
     findElement(_options: FindElementOptions): Promise<FindElementResponse>;
-    clickElement(_elementId: string, _app?: string): Promise<void>;
+    clickElement(_elementId: string, _app?: string): Promise<ClickResult>;
     typeInElement(_elementId: string, _text: string, _app?: string, _clearFirst?: boolean): Promise<void>;
     readClipboard(): Promise<string>;
     writeClipboard(text: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {