ucu-mcp 0.2.0 → 0.3.1

package/dist/src/platform/macos.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 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, UcuError, WindowNotFoundError } from "../util/errors.js";
+import { CaptureError, ElementNotFoundError, InputSynthesisError, PermissionError, PlatformError, TargetStaleError, UcuError, WindowNotFoundError } from "../util/errors.js";
 const execFileAsync = promisify(execFile);
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -40,6 +40,24 @@ function rethrowInputError(error, operation) {
         throw error;
     throw new InputSynthesisError(`${operation} failed: ${errorMessage(error)}`);
 }
+function normalizeAppName(name) {
+    return name.trim().toLowerCase();
+}
+function appNameMatches(processName, requestedApp) {
+    const process = normalizeAppName(processName);
+    const requested = normalizeAppName(requestedApp);
+    if (!process || !requested)
+        return false;
+    return process === requested ||
+        process.startsWith(`${requested} `) ||
+        process.startsWith(`${requested}-`) ||
+        process.includes(` ${requested} `);
+}
+function selectWindowForApp(windows, requestedApp) {
+    const requested = normalizeAppName(requestedApp);
+    return windows.find((window) => normalizeAppName(window.processName) === requested) ??
+        windows.find((window) => appNameMatches(window.processName, requestedApp));
+}
 export class MacOSPlatform {
     elementCache = new Map();
     elementCacheTtlMs = 30_000;
@@ -81,6 +99,18 @@ export class MacOSPlatform {
     isCacheEntryExpired(descriptor) {
         return Date.now() - descriptor.cachedAt > this.elementCacheTtlMs;
     }
+    // ── Target Validation ────────────────────────────────────────────────────
+    /** Validate that the active target window still exists. */
+    async validateActiveTarget() {
+        if (!this.activeTarget?.windowId)
+            return;
+        this.windowCache = undefined; // Bypass cache — stale detection must use fresh data
+        const windows = await this.listWindows(true);
+        const stillExists = windows.some(w => w.id === this.activeTarget.windowId);
+        if (!stillExists) {
+            throw new TargetStaleError(this.activeTarget.windowId);
+        }
+    }
     // ── Focus Management ────────────────────────────────────────────────────
     /** Save the current frontmost app/window so we can restore after an action. */
     async saveFocus() {
@@ -199,7 +229,6 @@ export class MacOSPlatform {
         return JSON.parse(out);
     }
     async focusApp(app) {
-        const appLower = app.toLowerCase();
         const escapedApp = app.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
         this.windowCache = undefined;
         try {
@@ -213,7 +242,7 @@ export class MacOSPlatform {
         const deadline = Date.now() + 3000;
         do {
             const windows = await this.listWindows(true);
-            target = windows.find((w) => w.processName.toLowerCase().includes(appLower));
+            target = selectWindowForApp(windows, app);
             if (target)
                 break;
             await new Promise((resolve) => setTimeout(resolve, 150));
@@ -222,10 +251,12 @@ export class MacOSPlatform {
             throw new WindowNotFoundError(app);
         }
         this.activeTarget = {
+            targetId: randomUUID(),
             appName: target.processName,
             pid: target.pid,
             windowId: target.id,
             title: target.title,
+            capturedAt: new Date().toISOString(),
         };
         return this.activeTarget;
     }
@@ -347,6 +378,9 @@ export class MacOSPlatform {
         }
     }
     async getWindowState(windowId, depth, includeBounds = true) {
+        if (!windowId || windowId === this.activeTarget?.windowId) {
+            await this.validateActiveTarget();
+        }
         const resolvedWindowId = windowId || this.activeTarget?.windowId;
         if (!resolvedWindowId) {
             throw new WindowNotFoundError("active target");
@@ -769,13 +803,24 @@ export class MacOSPlatform {
     // ── Accessibility (AX) Element Actions ───────────────────────────────────
     async findElement(options) {
         this.evictExpiredCacheEntries();
-        const { text, role, app, depth, includeBounds = true } = options;
+        const { text, role, app, depth, includeBounds = true, textMode = "contains", visibleOnly = false, value } = options;
         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, '\\$') : "";
+        // Pre-compile regex on TS side to validate syntax before passing to JXA
+        if (text && textMode === "regex") {
+            try {
+                new RegExp(text);
+            }
+            catch {
+                throw new PlatformError(`Invalid regex pattern: ${text}`);
+            }
+        }
+        const startTime = Date.now();
         const jxaScript = `
         var se = Application('System Events');
       function childElements(elem) {
@@ -784,14 +829,72 @@ export class MacOSPlatform {
         }
       }
         var results = [];
+      var scannedCount = 0;
+      var matchedCount = 0;
       var resultCount = [0];
       var maxResults = ${maxResults};
       var includeBounds = ${includeBounds ? "true" : "false"};
+      var visibleOnly = ${visibleOnly ? "true" : "false"};
+      var textMode = "${textMode}";
 
       var textFilter = ${text ? `"${escapedText}"` : "null"};
       var roleFilter = ${role ? `"${escapedRole}"` : "null"};
+      var valueFilter = ${value ? `"${escapedValue}"` : "null"};
+
+      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;
+        }
+      }
+
+      function textMatches(elemName, elemValue, elemDesc) {
+        if (textFilter === null) return true;
+        var sources = [elemName, elemValue, elemDesc];
+        if (textMode === "exact") {
+          var t = textFilter.toLowerCase();
+          for (var i = 0; i < sources.length; i++) {
+            if (sources[i].toLowerCase() === t) return true;
+          }
+          return false;
+        } else if (textMode === "regex") {
+          try {
+            var re = new RegExp(textFilter, "i");
+            for (var i = 0; i < sources.length; i++) {
+              if (re.test(sources[i])) return true;
+            }
+          } catch(e) {}
+          return false;
+        } else {
+          // contains (default)
+          var t = textFilter.toLowerCase();
+          for (var i = 0; i < sources.length; i++) {
+            if (sources[i].toLowerCase().indexOf(t) !== -1) return true;
+          }
+          return false;
+        }
+      }
+
+      function valueMatches(elemValue) {
+        if (valueFilter === null) return true;
+        if (textMode === "exact") {
+          return elemValue.toLowerCase() === valueFilter.toLowerCase();
+        } else if (textMode === "regex") {
+          try {
+            return new RegExp(valueFilter, "i").test(elemValue);
+          } catch(e) { return false; }
+        } else {
+          // contains (default)
+          return elemValue.toLowerCase().indexOf(valueFilter.toLowerCase()) !== -1;
+        }
+      }
 
       function matches(elem) {
+        scannedCount++;
         var elemName = '';
         var elemRole = '';
         var elemDesc = '';
@@ -801,17 +904,14 @@ export class MacOSPlatform {
         try { elemDesc = elem.description() || ''; } catch(e) {}
         try { var v = elem.value(); elemValue = (v !== undefined && v !== null) ? String(v) : ''; } catch(e) {}
 
-        if (textFilter !== null) {
-          var t = textFilter.toLowerCase();
-          if (elemName.toLowerCase().indexOf(t) === -1 &&
-              elemValue.toLowerCase().indexOf(t) === -1 &&
-              elemDesc.toLowerCase().indexOf(t) === -1) {
-            return false;
-          }
-        }
+        if (visibleOnly && !isVisible(elem)) return false;
+
+        if (!textMatches(elemName, elemValue, elemDesc)) return false;
         if (roleFilter !== null) {
           if (elemRole !== roleFilter) return false;
         }
+        if (!valueMatches(elemValue)) return false;
+        matchedCount++;
         return true;
       }
 
@@ -894,15 +994,16 @@ export class MacOSPlatform {
         }
       } catch(e) {}
 
-      JSON.stringify(results);
+      JSON.stringify({results: results, scannedCount: scannedCount, matchedCount: matchedCount});
     `;
         try {
             const out = execFileSync("osascript", [
                 "-l", "JavaScript",
                 "-e", jxaScript,
             ], { encoding: "utf-8", timeout: 30000 }).trim();
-            const results = JSON.parse(out);
-            for (const result of results) {
+            const parsed = JSON.parse(out);
+            const durationMs = Date.now() - startTime;
+            for (const result of parsed.results) {
                 const appName = effectiveApp || result.id.split("/")[0] || "";
                 this.elementCache.set(result.id, {
                     elementId: result.id,
@@ -918,7 +1019,32 @@ export class MacOSPlatform {
                 });
             }
             this.evictOverflowCacheEntries();
-            return results;
+            let finalResults = parsed.results;
+            if (options.near) {
+                const nx = options.near.x;
+                const ny = options.near.y;
+                finalResults = [...finalResults].sort((a, b) => {
+                    const acx = (a.bounds?.x ?? 0) + (a.bounds?.width ?? 0) / 2;
+                    const acy = (a.bounds?.y ?? 0) + (a.bounds?.height ?? 0) / 2;
+                    const bcx = (b.bounds?.x ?? 0) + (b.bounds?.width ?? 0) / 2;
+                    const bcy = (b.bounds?.y ?? 0) + (b.bounds?.height ?? 0) / 2;
+                    return Math.hypot(acx - nx, acy - ny) - Math.hypot(bcx - nx, bcy - ny);
+                });
+            }
+            if (typeof options.index === "number") {
+                finalResults = options.index >= 0 && options.index < finalResults.length
+                    ? [finalResults[options.index]]
+                    : [];
+            }
+            return {
+                results: finalResults,
+                metrics: {
+                    scannedCount: parsed.scannedCount,
+                    matchedCount: parsed.matchedCount,
+                    durationMs,
+                    truncated: parsed.results.length >= maxResults,
+                },
+            };
         }
         catch (error) {
             rethrowAccessibilityError(error, "find_element");
@@ -1397,6 +1523,24 @@ export class MacOSPlatform {
             rethrowElementActionError(error, "type_in_element", elementId);
         }
     }
+    // ── Clipboard ───────────────────────────────────────────────────────────
+    async readClipboard() {
+        try {
+            const out = execFileSync("pbpaste", [], { encoding: "utf-8", timeout: 5000 });
+            return out;
+        }
+        catch (error) {
+            throw new PlatformError(`read_clipboard failed: ${errorMessage(error)}`);
+        }
+    }
+    async writeClipboard(text) {
+        try {
+            execFileSync("pbcopy", [], { input: text, encoding: "utf-8", timeout: 5000 });
+        }
+        catch (error) {
+            throw new PlatformError(`write_clipboard failed: ${errorMessage(error)}`);
+        }
+    }
     async setElementValue(elementId, value, app) {
         this.evictExpiredCacheEntries();
         const effectiveApp = app || this.activeTarget?.appName;

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

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

package/dist/src/platform/windows.js

@@ -1,3 +1,17 @@
+import { execFileSync } from "node:child_process";
+import { PlatformError } from "../util/errors.js";
+function runPowerShell(script, input) {
+    try {
+        return execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+            encoding: "utf-8",
+            timeout: 10000,
+            ...(input !== undefined ? { input } : {}),
+        });
+    }
+    catch (error) {
+        throw new PlatformError(`PowerShell failed: ${error.message}`);
+    }
+}
 export class WindowsPlatform {
     async screenshot(_display, _region) {
         throw new Error("Not implemented: Windows screenshot");
@@ -45,4 +59,23 @@ export class WindowsPlatform {
     async typeInElement(_elementId, _text, _app, _clearFirst) {
         throw new Error("Not implemented: Windows typeInElement");
     }
+    async readClipboard() {
+        try {
+            // Get-Clipboard returns the clipboard text; trim trailing newline PowerShell adds
+            const out = runPowerShell("Get-Clipboard -Raw");
+            return out;
+        }
+        catch (error) {
+            throw new PlatformError(`read_clipboard failed: ${error.message}`);
+        }
+    }
+    async writeClipboard(text) {
+        try {
+            // Pipe the text to Set-Clipboard via stdin to avoid shell quoting issues
+            runPowerShell("$stdin = [Console]::In.ReadToEnd(); Set-Clipboard -Value $stdin", text);
+        }
+        catch (error) {
+            throw new PlatformError(`write_clipboard failed: ${error.message}`);
+        }
+    }
 }

package/dist/src/safety/guard.d.ts

@@ -22,6 +22,11 @@ export interface SafetyGuardConfig {
     /** Minimum milliseconds between consecutive actions (default 100). */
     rateLimitMs?: number;
 }
+/** Actions that observe UI/system state without altering it. */
+export declare const OBSERVE_ACTIONS: ReadonlySet<string>;
+/** Actions that synthesize user input — need full user-activity protection. */
+export declare const INPUT_ACTIONS: ReadonlySet<string>;
+export declare function classifyAction(action: string): "observe" | "input" | "other";
 export declare class SafetyGuard {
     private readonly blockedKeys;
     private readonly skippedWindows;
@@ -40,7 +45,9 @@ export declare class SafetyGuard {
      *                - "key":         { keys: string[] }
      *                - any action:    { windowTitle?: string }
      */
-    checkAction(action: string, params?: Record<string, unknown>): SafetyCheckResult;
+    checkAction(action: string, params?: Record<string, unknown>, options?: {
+        skipUserActivityPause?: boolean;
+    }): SafetyCheckResult;
     /** Record that the user performed an activity (mouse/keyboard). */
     recordUserActivity(): void;
     /** Set the pause duration after user activity (default 2000ms). */

package/dist/src/safety/guard.js

@@ -84,6 +84,45 @@ function normalizeShortcut(raw) {
         .join("+");
 }
 // ---------------------------------------------------------------------------
+// Action classification (observe vs input)
+// ---------------------------------------------------------------------------
+/** Actions that observe UI/system state without altering it. */
+export const OBSERVE_ACTIONS = new Set([
+    "screenshot",
+    "list_windows",
+    "list_apps",
+    "get_window_state",
+    "get_screen_size",
+    "get_cursor_position",
+    "ocr",
+    "find_element",
+    "wait",
+    "wait_for_element",
+    "doctor",
+    "clipboard_read",
+]);
+/** Actions that synthesize user input — need full user-activity protection. */
+export const INPUT_ACTIONS = new Set([
+    "click",
+    "double_click",
+    "scroll",
+    "drag",
+    "move",
+    "type_text",
+    "press_key",
+    "click_element",
+    "type_in_element",
+    "set_value",
+    "clipboard_write",
+]);
+export function classifyAction(action) {
+    if (OBSERVE_ACTIONS.has(action))
+        return "observe";
+    if (INPUT_ACTIONS.has(action))
+        return "input";
+    return "other";
+}
+// ---------------------------------------------------------------------------
 // SafetyGuard
 // ---------------------------------------------------------------------------
 export class SafetyGuard {
@@ -123,7 +162,7 @@ export class SafetyGuard {
      *                - "key":         { keys: string[] }
      *                - any action:    { windowTitle?: string }
      */
-    checkAction(action, params = {}) {
+    checkAction(action, params = {}, options = {}) {
         // 1. Key blocklist -------------------------------------------------------
         if (action === "key" || action === "press_key") {
             const keys = params.keys;
@@ -164,7 +203,7 @@ export class SafetyGuard {
             }
         }
         // 4. Text injection scan --------------------------------------------------
-        if (!this.allowUnsafeText && (action === "type" || action === "type_text" || action === "type_in_element" || action === "set_value")) {
+        if (!this.allowUnsafeText && (action === "type" || action === "type_text" || action === "type_in_element" || action === "set_value" || action === "clipboard_write")) {
             const text = typeof params.text === "string"
                 ? params.text
                 : typeof params.value === "string"
@@ -191,8 +230,8 @@ export class SafetyGuard {
             };
         }
         this.lastActionTime = now;
-        // 6. User activity pause --------------------------------------------------
-        if (this.isUserActivityPauseActive()) {
+        // 6. User activity pause (skipped for observe-class actions) -----------------
+        if (!options.skipUserActivityPause && this.isUserActivityPauseActive()) {
             return {
                 allowed: false,
                 reason: `User activity detected — pausing automation for ${this.userActivityPauseMs}ms`,

package/dist/src/util/errors.d.ts

@@ -2,48 +2,70 @@
  * Error taxonomy for UCU-MCP.
  *
  * All errors inherit from UcuError and are categorized by:
- *   - code: machine-readable error code
+ *   - code: machine-readable error code (also exposed via toJSON)
  *   - retryable: whether the operation can be retried
  */
 export declare class UcuError extends Error {
+    /** Default error code for this class. Subclasses override. */
+    static readonly defaultCode: string;
     readonly code: string;
     readonly retryable: boolean;
     constructor(message: string, code?: string, retryable?: boolean);
+    /** Serialize for MCP response / JSON.stringify. */
+    toJSON(): {
+        name: string;
+        code: string;
+        retryable: boolean;
+        message: string;
+    };
 }
 /**
  * Native API call failed (permissions, OS error, timeout).
  */
 export declare class PlatformError extends UcuError {
+    static readonly defaultCode = "PLATFORM_ERROR";
     constructor(message: string, retryable?: boolean);
 }
 /**
  * Action blocked by safety guard.
  */
 export declare class SafetyError extends UcuError {
+    static readonly defaultCode = "SAFETY_BLOCKED";
     constructor(message: string);
 }
 /**
  * Missing OS accessibility/screen-recording permissions.
  */
 export declare class PermissionError extends UcuError {
+    static readonly defaultCode = "PERMISSION_DENIED";
     constructor(permission: string, platform: string);
 }
 /**
  * Requested window ID no longer exists.
  */
 export declare class WindowNotFoundError extends UcuError {
+    static readonly defaultCode = "WINDOW_NOT_FOUND";
+    constructor(windowId: string);
+}
+/**
+ * Active target window is no longer available.
+ */
+export declare class TargetStaleError extends UcuError {
+    static readonly defaultCode = "TARGET_STALE";
     constructor(windowId: string);
 }
 /**
  * Requested accessibility element ID no longer resolves.
  */
 export declare class ElementNotFoundError extends UcuError {
+    static readonly defaultCode = "ELEMENT_NOT_FOUND";
     constructor(elementId: string);
 }
 /**
  * Click/scroll target is outside screen bounds.
  */
 export declare class CoordinateError extends UcuError {
+    static readonly defaultCode = "COORDINATE_OUT_OF_BOUNDS";
     constructor(x: number, y: number, bounds: {
         width: number;
         height: number;
@@ -53,6 +75,7 @@ export declare class CoordinateError extends UcuError {
  * Keystroke or mouse event injection failed.
  */
 export declare class InputSynthesisError extends UcuError {
+    static readonly defaultCode = "INPUT_FAILED";
     constructor(message: string);
 }
 /**
@@ -60,11 +83,13 @@ export declare class InputSynthesisError extends UcuError {
  * implementation does not support.
  */
 export declare class UnsupportedParameterError extends UcuError {
+    static readonly defaultCode = "UNSUPPORTED_PARAMETER";
     constructor(message: string);
 }
 /**
  * Screenshot or window-state capture failed.
  */
 export declare class CaptureError extends UcuError {
+    static readonly defaultCode = "CAPTURE_FAILED";
     constructor(message: string);
 }

package/dist/src/util/errors.js

@@ -2,21 +2,35 @@
  * Error taxonomy for UCU-MCP.
  *
  * All errors inherit from UcuError and are categorized by:
- *   - code: machine-readable error code
+ *   - code: machine-readable error code (also exposed via toJSON)
  *   - retryable: whether the operation can be retried
  */
 // ---------------------------------------------------------------------------
 // Base Error Class
 // ---------------------------------------------------------------------------
 export class UcuError extends Error {
+    /** Default error code for this class. Subclasses override. */
+    static defaultCode = "UCU_ERROR";
     code;
     retryable;
-    constructor(message, code = "UCU_ERROR", retryable = false) {
+    constructor(message, code, retryable = false) {
         super(message);
+        if (code === undefined) {
+            code = this.constructor.defaultCode;
+        }
         this.name = this.constructor.name;
         this.code = code;
         this.retryable = retryable;
     }
+    /** Serialize for MCP response / JSON.stringify. */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            retryable: this.retryable,
+            message: this.message,
+        };
+    }
 }
 // ---------------------------------------------------------------------------
 // Platform Errors
@@ -25,8 +39,9 @@ export class UcuError extends Error {
  * Native API call failed (permissions, OS error, timeout).
  */
 export class PlatformError extends UcuError {
+    static defaultCode = "PLATFORM_ERROR";
     constructor(message, retryable = true) {
-        super(message, "PLATFORM_ERROR", retryable);
+        super(message, PlatformError.defaultCode, retryable);
     }
 }
 // ---------------------------------------------------------------------------
@@ -36,8 +51,9 @@ export class PlatformError extends UcuError {
  * Action blocked by safety guard.
  */
 export class SafetyError extends UcuError {
+    static defaultCode = "SAFETY_BLOCKED";
     constructor(message) {
-        super(message, "SAFETY_BLOCKED", false);
+        super(message, SafetyError.defaultCode, false);
     }
 }
 // ---------------------------------------------------------------------------
@@ -47,8 +63,9 @@ export class SafetyError extends UcuError {
  * Missing OS accessibility/screen-recording permissions.
  */
 export class PermissionError extends UcuError {
+    static defaultCode = "PERMISSION_DENIED";
     constructor(permission, platform) {
-        super(getPermissionMessage(permission, platform), "PERMISSION_DENIED", false);
+        super(getPermissionMessage(permission, platform), PermissionError.defaultCode, false);
     }
 }
 function getPermissionMessage(permission, platform) {
@@ -64,16 +81,27 @@ function getPermissionMessage(permission, platform) {
  * Requested window ID no longer exists.
  */
 export class WindowNotFoundError extends UcuError {
+    static defaultCode = "WINDOW_NOT_FOUND";
+    constructor(windowId) {
+        super(`Window ${windowId} not found. It may have been closed. Run list_windows to get fresh IDs.`, WindowNotFoundError.defaultCode, false);
+    }
+}
+/**
+ * Active target window is no longer available.
+ */
+export class TargetStaleError extends UcuError {
+    static defaultCode = "TARGET_STALE";
     constructor(windowId) {
-        super(`Window ${windowId} not found. It may have been closed. Run list_windows to get fresh IDs.`, "WINDOW_NOT_FOUND", false);
+        super(`Active target window ${windowId} is no longer available. Run focus_app or list_windows to refresh.`, TargetStaleError.defaultCode, false);
     }
 }
 /**
  * Requested accessibility element ID no longer resolves.
  */
 export class ElementNotFoundError extends UcuError {
+    static defaultCode = "ELEMENT_NOT_FOUND";
     constructor(elementId) {
-        super(`Element ${elementId} not found. It may have been removed or invalidated. Run find_element to get a fresh ID.`, "ELEMENT_NOT_FOUND", false);
+        super(`Element ${elementId} not found. It may have been removed or invalidated. Run find_element to get a fresh ID.`, ElementNotFoundError.defaultCode, false);
     }
 }
 // ---------------------------------------------------------------------------
@@ -83,16 +111,18 @@ export class ElementNotFoundError extends UcuError {
  * Click/scroll target is outside screen bounds.
  */
 export class CoordinateError extends UcuError {
+    static defaultCode = "COORDINATE_OUT_OF_BOUNDS";
     constructor(x, y, bounds) {
-        super(`Coordinate (${x}, ${y}) is outside screen bounds (0-${bounds.width}, 0-${bounds.height}).`, "COORDINATE_OUT_OF_BOUNDS", false);
+        super(`Coordinate (${x}, ${y}) is outside screen bounds (0-${bounds.width}, 0-${bounds.height}).`, CoordinateError.defaultCode, false);
     }
 }
 /**
  * Keystroke or mouse event injection failed.
  */
 export class InputSynthesisError extends UcuError {
+    static defaultCode = "INPUT_FAILED";
     constructor(message) {
-        super(message, "INPUT_FAILED", true);
+        super(message, InputSynthesisError.defaultCode, true);
     }
 }
 /**
@@ -100,8 +130,9 @@ export class InputSynthesisError extends UcuError {
  * implementation does not support.
  */
 export class UnsupportedParameterError extends UcuError {
+    static defaultCode = "UNSUPPORTED_PARAMETER";
     constructor(message) {
-        super(message, "UNSUPPORTED_PARAMETER", false);
+        super(message, UnsupportedParameterError.defaultCode, false);
     }
 }
 // ---------------------------------------------------------------------------
@@ -111,7 +142,8 @@ export class UnsupportedParameterError extends UcuError {
  * Screenshot or window-state capture failed.
  */
 export class CaptureError extends UcuError {
+    static defaultCode = "CAPTURE_FAILED";
     constructor(message) {
-        super(message, "CAPTURE_FAILED", true);
+        super(message, CaptureError.defaultCode, true);
     }
 }