appium-uiwatchers-plugin 1.0.0 → 1.0.1

package/README.md

@@ -4,7 +4,6 @@
 [![Appium 3.x](https://img.shields.io/badge/Appium-3.x-purple.svg)](https://appium.io/)
 [![Node.js 18+](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
 [![npm version](https://img.shields.io/npm/v/appium-uiwatchers-plugin.svg)](https://www.npmjs.com/package/appium-uiwatchers-plugin)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/rajvinodh/appium-uiwatchers-plugin/ci.yml?branch=main)](https://github.com/rajvinodh/appium-uiwatchers-plugin/actions)
 
 ## Introduction
 
@@ -12,6 +11,12 @@ Mobile apps often display unexpected UI elements — cookie consent dialogs, per
 
 This plugin provides a centralized, declarative way to handle these interruptions automatically.
 
+## Motivation
+
+Android's UiAutomator 1.0 had a [UiWatcher](https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher) API that automatically handled unexpected dialogs during tests. When the framework couldn't find an element, it would run registered watchers to dismiss blockers like ANR dialogs or permission prompts.
+
+This feature was deprecated and never made it to UiAutomator 2.0. This plugin brings the same concept to Appium — working across both Android and iOS.
+
 ## Features
 
 - **Zero Wait Overhead** — No waiting for UI elements that may never appear
@@ -25,7 +30,7 @@ This plugin provides a centralized, declarative way to handle these interruption
 
 ## Installation
 
-### From npm (coming soon)
+### From npm
 
 ```bash
 appium plugin install appium-uiwatchers-plugin

package/lib/commands/clear.d.ts

@@ -0,0 +1,12 @@
+/**
+ * clearAllUIWatchers command implementation
+ */
+import type { WatcherStore } from '../watcher-store.js';
+import type { ClearAllWatchersResult } from '../types.js';
+/**
+ * Clear all UI watchers from the session
+ * @param store - Watcher store instance
+ * @returns Clear result with count of removed watchers
+ */
+export declare function clearAllUIWatchers(store: WatcherStore): Promise<ClearAllWatchersResult>;
+//# sourceMappingURL=clear.d.ts.map

package/lib/commands/clear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../src/commands/clear.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAI1D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAY7F"}

package/lib/commands/clear.js

@@ -0,0 +1,22 @@
+/**
+ * clearAllUIWatchers command implementation
+ */
+import { logger } from '@appium/support';
+const log = logger.getLogger('AppiumUIWatchers');
+/**
+ * Clear all UI watchers from the session
+ * @param store - Watcher store instance
+ * @returns Clear result with count of removed watchers
+ */
+export async function clearAllUIWatchers(store) {
+    // Get count before clearing
+    const count = store.clear();
+    // Log successful clear
+    log.info(`[UIWatchers] All UI watchers cleared (removed ${count} watchers)`);
+    // Return success response
+    return {
+        success: true,
+        removedCount: count,
+    };
+}
+//# sourceMappingURL=clear.js.map

package/lib/commands/clear.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear.js","sourceRoot":"","sources":["../../src/commands/clear.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAIzC,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAEjD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAAmB;IAC1D,4BAA4B;IAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;IAE5B,uBAAuB;IACvB,GAAG,CAAC,IAAI,CAAC,iDAAiD,KAAK,YAAY,CAAC,CAAC;IAE7E,0BAA0B;IAC1B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,YAAY,EAAE,KAAK;KACpB,CAAC;AACJ,CAAC"}

package/lib/commands/list.d.ts

@@ -0,0 +1,12 @@
+/**
+ * listUIWatchers command implementation
+ */
+import type { WatcherStore } from '../watcher-store.js';
+import type { ListWatchersResult } from '../types.js';
+/**
+ * List all active UI watchers with their state
+ * @param store - Watcher store instance
+ * @returns List of all active watchers
+ */
+export declare function listUIWatchers(store: WatcherStore): Promise<ListWatchersResult>;
+//# sourceMappingURL=list.d.ts.map

package/lib/commands/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/commands/list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAUrF"}

package/lib/commands/list.js

@@ -0,0 +1,19 @@
+/**
+ * listUIWatchers command implementation
+ */
+/**
+ * List all active UI watchers with their state
+ * @param store - Watcher store instance
+ * @returns List of all active watchers
+ */
+export async function listUIWatchers(store) {
+    // Get all active watchers (this automatically filters out expired ones)
+    const activeWatchers = store.getActiveWatchers();
+    // Return success response
+    return {
+        success: true,
+        watchers: activeWatchers,
+        totalCount: activeWatchers.length,
+    };
+}
+//# sourceMappingURL=list.js.map

package/lib/commands/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/commands/list.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,KAAmB;IACtD,wEAAwE;IACxE,MAAM,cAAc,GAAG,KAAK,CAAC,iBAAiB,EAAE,CAAC;IAEjD,0BAA0B;IAC1B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,cAAc;QACxB,UAAU,EAAE,cAAc,CAAC,MAAM;KAClC,CAAC;AACJ,CAAC"}

package/lib/commands/register.d.ts

@@ -0,0 +1,13 @@
+/**
+ * registerUIWatcher command implementation
+ */
+import type { WatcherStore } from '../watcher-store.js';
+import type { UIWatcher, RegisterWatcherResult } from '../types.js';
+/**
+ * Register a new UI watcher
+ * @param store - Watcher store instance
+ * @param params - Watcher registration parameters
+ * @returns Registration result
+ */
+export declare function registerUIWatcher(store: WatcherStore, params: UIWatcher): Promise<RegisterWatcherResult>;
+//# sourceMappingURL=register.d.ts.map

package/lib/commands/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/commands/register.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAKpE;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,qBAAqB,CAAC,CA0BhC"}

package/lib/commands/register.js

@@ -0,0 +1,34 @@
+/**
+ * registerUIWatcher command implementation
+ */
+import { logger } from '@appium/support';
+import { validateWatcherParams } from '../validators.js';
+const log = logger.getLogger('AppiumUIWatchers');
+/**
+ * Register a new UI watcher
+ * @param store - Watcher store instance
+ * @param params - Watcher registration parameters
+ * @returns Registration result
+ */
+export async function registerUIWatcher(store, params) {
+    // Get configuration from store
+    const config = store.getConfig();
+    // Validate parameters with configured max duration
+    validateWatcherParams(params, config.maxDurationMs);
+    // Add watcher to store (this will throw if validation fails at store level)
+    const watcherState = store.add(params);
+    // Log successful registration
+    log.info(`[UIWatchers] UIWatcher '${params.name}' registered (priority=${watcherState.priority}, duration=${params.duration}ms)`);
+    // Return success response
+    return {
+        success: true,
+        watcher: {
+            name: watcherState.name,
+            priority: watcherState.priority,
+            registeredAt: watcherState.registeredAt,
+            expiresAt: watcherState.expiresAt,
+            status: watcherState.status,
+        },
+    };
+}
+//# sourceMappingURL=register.js.map

package/lib/commands/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/commands/register.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAGzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAmB,EACnB,MAAiB;IAEjB,+BAA+B;IAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;IAEjC,mDAAmD;IACnD,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;IAEpD,4EAA4E;IAC5E,MAAM,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAEvC,8BAA8B;IAC9B,GAAG,CAAC,IAAI,CACN,2BAA2B,MAAM,CAAC,IAAI,0BAA0B,YAAY,CAAC,QAAQ,cAAc,MAAM,CAAC,QAAQ,KAAK,CACxH,CAAC;IAEF,0BAA0B;IAC1B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP,IAAI,EAAE,YAAY,CAAC,IAAI;YACvB,QAAQ,EAAE,YAAY,CAAC,QAAQ;YAC/B,YAAY,EAAE,YAAY,CAAC,YAAY;YACvC,SAAS,EAAE,YAAY,CAAC,SAAS;YACjC,MAAM,EAAE,YAAY,CAAC,MAAM;SAC5B;KACF,CAAC;AACJ,CAAC"}

package/lib/commands/toggle.d.ts

@@ -0,0 +1,18 @@
+/**
+ * disableUIWatchers and enableUIWatchers command implementations
+ */
+import type { WatcherStore } from '../watcher-store.js';
+import type { ToggleWatchersResult } from '../types.js';
+/**
+ * Disable all UI watcher checking
+ * @param store - Watcher store instance
+ * @returns Disable result
+ */
+export declare function disableUIWatchers(store: WatcherStore): Promise<ToggleWatchersResult>;
+/**
+ * Enable all UI watcher checking
+ * @param store - Watcher store instance
+ * @returns Enable result
+ */
+export declare function enableUIWatchers(store: WatcherStore): Promise<ToggleWatchersResult>;
+//# sourceMappingURL=toggle.d.ts.map

package/lib/commands/toggle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle.d.ts","sourceRoot":"","sources":["../../src/commands/toggle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIxD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAU1F;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAUzF"}

package/lib/commands/toggle.js

@@ -0,0 +1,34 @@
+/**
+ * disableUIWatchers and enableUIWatchers command implementations
+ */
+import { logger } from '@appium/support';
+const log = logger.getLogger('AppiumUIWatchers');
+/**
+ * Disable all UI watcher checking
+ * @param store - Watcher store instance
+ * @returns Disable result
+ */
+export async function disableUIWatchers(store) {
+    store.disable();
+    // Log successful disable
+    log.info('[UIWatchers] All UI watchers disabled');
+    return {
+        success: true,
+        message: 'All UI watchers disabled',
+    };
+}
+/**
+ * Enable all UI watcher checking
+ * @param store - Watcher store instance
+ * @returns Enable result
+ */
+export async function enableUIWatchers(store) {
+    store.enable();
+    // Log successful enable
+    log.info('[UIWatchers] All UI watchers enabled');
+    return {
+        success: true,
+        message: 'All UI watchers enabled',
+    };
+}
+//# sourceMappingURL=toggle.js.map

package/lib/commands/toggle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle.js","sourceRoot":"","sources":["../../src/commands/toggle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAIzC,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAEjD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,KAAmB;IACzD,KAAK,CAAC,OAAO,EAAE,CAAC;IAEhB,yBAAyB;IACzB,GAAG,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;IAElD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,0BAA0B;KACpC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAmB;IACxD,KAAK,CAAC,MAAM,EAAE,CAAC;IAEf,wBAAwB;IACxB,GAAG,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;IAEjD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,yBAAyB;KACnC,CAAC;AACJ,CAAC"}

package/lib/commands/unregister.d.ts

@@ -0,0 +1,13 @@
+/**
+ * unregisterUIWatcher command implementation
+ */
+import type { WatcherStore } from '../watcher-store.js';
+import type { UnregisterWatcherResult } from '../types.js';
+/**
+ * Unregister a specific UI watcher by name
+ * @param store - Watcher store instance
+ * @param name - Name of the watcher to remove
+ * @returns Unregistration result
+ */
+export declare function unregisterUIWatcher(store: WatcherStore, name: string): Promise<UnregisterWatcherResult>;
+//# sourceMappingURL=unregister.d.ts.map

package/lib/commands/unregister.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unregister.d.ts","sourceRoot":"","sources":["../../src/commands/unregister.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAI3D;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,uBAAuB,CAAC,CAuBlC"}

package/lib/commands/unregister.js

@@ -0,0 +1,32 @@
+/**
+ * unregisterUIWatcher command implementation
+ */
+import { logger } from '@appium/support';
+const log = logger.getLogger('AppiumUIWatchers');
+/**
+ * Unregister a specific UI watcher by name
+ * @param store - Watcher store instance
+ * @param name - Name of the watcher to remove
+ * @returns Unregistration result
+ */
+export async function unregisterUIWatcher(store, name) {
+    // Validate name parameter
+    if (!name || typeof name !== 'string') {
+        throw new Error('UIWatcher name is required');
+    }
+    // Check if watcher exists
+    const watcher = store.get(name);
+    if (!watcher) {
+        throw new Error(`UIWatcher '${name}' not found`);
+    }
+    // Remove watcher from store
+    store.remove(name);
+    // Log successful removal
+    log.info(`[UIWatchers] UIWatcher '${name}' unregistered`);
+    // Return success response
+    return {
+        success: true,
+        removed: name,
+    };
+}
+//# sourceMappingURL=unregister.js.map

package/lib/commands/unregister.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unregister.js","sourceRoot":"","sources":["../../src/commands/unregister.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAIzC,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAmB,EACnB,IAAY;IAEZ,0BAA0B;IAC1B,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAChD,CAAC;IAED,0BAA0B;IAC1B,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,aAAa,CAAC,CAAC;IACnD,CAAC;IAED,4BAA4B;IAC5B,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAEnB,yBAAyB;IACzB,GAAG,CAAC,IAAI,CAAC,2BAA2B,IAAI,gBAAgB,CAAC,CAAC;IAE1D,0BAA0B;IAC1B,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/lib/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Configuration module for UI Watchers Plugin
+ */
+/**
+ * Plugin configuration interface
+ */
+export interface PluginConfig {
+    /** Maximum number of watchers allowed per session (1-20) */
+    maxWatchers?: number;
+    /** Maximum duration per watcher in milliseconds (1000-600000) */
+    maxDurationMs?: number;
+    /** Maximum element references to cache for stale recovery (10-200) */
+    maxCacheEntries?: number;
+    /** TTL for cached element references in milliseconds (5000-300000) */
+    elementTtlMs?: number;
+}
+/**
+ * Default configuration values
+ */
+export declare const DefaultPluginConfig: Required<PluginConfig>;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,YAAY,CAKtD,CAAC"}

package/lib/config.js

@@ -0,0 +1,13 @@
+/**
+ * Configuration module for UI Watchers Plugin
+ */
+/**
+ * Default configuration values
+ */
+export const DefaultPluginConfig = {
+    maxWatchers: 5,
+    maxDurationMs: 60000,
+    maxCacheEntries: 50,
+    elementTtlMs: 60000,
+};
+//# sourceMappingURL=config.js.map

package/lib/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmBH;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA2B;IACzD,WAAW,EAAE,CAAC;IACd,aAAa,EAAE,KAAK;IACpB,eAAe,EAAE,EAAE;IACnB,YAAY,EAAE,KAAK;CACpB,CAAC"}

package/lib/element-cache.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Element Reference Cache for StaleElement Recovery
+ *
+ * This module provides caching of element locators to enable automatic recovery
+ * from StaleElementReferenceException on element action commands.
+ */
+import type { CachedRef } from './types.js';
+import type { PluginConfig } from './config.js';
+import { type ElementObject } from './utils.js';
+/**
+ * Configuration for ElementReferenceCache
+ */
+export interface CacheConfig {
+    maxCacheEntries: number;
+    elementTtlMs: number;
+}
+/**
+ * ElementReferenceCache manages cached element locators for stale element recovery.
+ *
+ * Features:
+ * - Caches element locators on successful findElement/findElements
+ * - Provides element ID mapping for recovered elements
+ * - Supports transitive mapping updates (abc→efg, efg→hij => abc→hij)
+ * - LRU eviction when max entries reached
+ * - TTL-based expiry for old entries
+ */
+export declare class ElementReferenceCache {
+    /** Cache storage: elementId → CachedRef */
+    private cache;
+    /** Element ID mappings: oldId → newId */
+    private idMappings;
+    /** Reverse index for transitive updates: newId → Set<oldId> */
+    private reverseIndex;
+    /** LRU order tracking (most recent at end) */
+    private accessOrder;
+    /** Configuration */
+    private config;
+    constructor(config: Required<PluginConfig>);
+    /**
+     * Cache an element reference from findElement
+     */
+    cacheElement(elementId: string, using: string, value: string): void;
+    /**
+     * Cache element references from findElements
+     * Each element is cached with its index position
+     */
+    cacheElements(elements: ElementObject[], using: string, value: string): void;
+    /**
+     * Get cached reference for an element
+     * Returns undefined if not found or expired
+     */
+    getRef(elementId: string): CachedRef | undefined;
+    /**
+     * Create element ID mapping with transitive update
+     *
+     * When we map oldId → newId, we also update any existing mappings
+     * that point to oldId to instead point to newId.
+     *
+     * Example:
+     *   Existing: abc → efg
+     *   New mapping: efg → hij
+     *   Result: abc → hij, efg → hij
+     */
+    setMapping(oldId: string, newId: string): void;
+    /**
+     * Get mapped element ID if exists
+     * Returns the new ID if a mapping exists, otherwise returns undefined
+     */
+    getMappedId(elementId: string): string | undefined;
+    /**
+     * Remove expired entries from cache
+     */
+    cleanup(): void;
+    /**
+     * Clear all cache entries and mappings
+     */
+    clear(): void;
+    /**
+     * Get current cache size
+     */
+    get size(): number;
+    /**
+     * Get current mappings count
+     */
+    get mappingsCount(): number;
+    private addToCache;
+    private removeFromCache;
+    private evictLRU;
+    private updateAccessOrder;
+    private isExpired;
+    private addToReverseIndex;
+}
+//# sourceMappingURL=element-cache.d.ts.map

package/lib/element-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-cache.d.ts","sourceRoot":"","sources":["../src/element-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAuC,MAAM,YAAY,CAAC;AACjF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAIlE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAqB;IAChC,2CAA2C;IAC3C,OAAO,CAAC,KAAK,CAAyB;IAEtC,yCAAyC;IACzC,OAAO,CAAC,UAAU,CAAsB;IAExC,+DAA+D;IAC/D,OAAO,CAAC,YAAY,CAA2B;IAE/C,8CAA8C;IAC9C,OAAO,CAAC,WAAW,CAAW;IAE9B,oBAAoB;IACpB,OAAO,CAAC,MAAM,CAAc;gBAEhB,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC;IAW1C;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAYnE;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAqB5E;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAgBhD;;;;;;;;;;OAUG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAqB9C;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIlD;;OAEG;IACH,OAAO,IAAI,IAAI;IAmBf;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAMD,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,iBAAiB;CAM1B"}

package/lib/element-cache.js

@@ -0,0 +1,207 @@
+/**
+ * Element Reference Cache for StaleElement Recovery
+ *
+ * This module provides caching of element locators to enable automatic recovery
+ * from StaleElementReferenceException on element action commands.
+ */
+import { logger } from '@appium/support';
+import { extractElementId } from './utils.js';
+const log = logger.getLogger('AppiumUIWatchers');
+/**
+ * ElementReferenceCache manages cached element locators for stale element recovery.
+ *
+ * Features:
+ * - Caches element locators on successful findElement/findElements
+ * - Provides element ID mapping for recovered elements
+ * - Supports transitive mapping updates (abc→efg, efg→hij => abc→hij)
+ * - LRU eviction when max entries reached
+ * - TTL-based expiry for old entries
+ */
+export class ElementReferenceCache {
+    constructor(config) {
+        this.cache = new Map();
+        this.idMappings = new Map();
+        this.reverseIndex = new Map();
+        this.accessOrder = [];
+        this.config = {
+            maxCacheEntries: config.maxCacheEntries,
+            elementTtlMs: config.elementTtlMs,
+        };
+    }
+    /**
+     * Cache an element reference from findElement
+     */
+    cacheElement(elementId, using, value) {
+        const ref = {
+            using,
+            value,
+            source: 'findElement',
+            createdAt: Date.now(),
+        };
+        this.addToCache(elementId, ref);
+        log.debug(`[UIWatchers] Cached element reference: ${elementId} (${using}=${value})`);
+    }
+    /**
+     * Cache element references from findElements
+     * Each element is cached with its index position
+     */
+    cacheElements(elements, using, value) {
+        for (let i = 0; i < elements.length; i++) {
+            const element = elements[i];
+            const elementId = extractElementId(element);
+            if (!elementId)
+                continue;
+            const ref = {
+                using,
+                value,
+                index: i,
+                source: 'findElements',
+                createdAt: Date.now(),
+            };
+            this.addToCache(elementId, ref);
+        }
+        log.debug(`[UIWatchers] Cached ${elements.length} element references from findElements (${using}=${value})`);
+    }
+    /**
+     * Get cached reference for an element
+     * Returns undefined if not found or expired
+     */
+    getRef(elementId) {
+        const ref = this.cache.get(elementId);
+        if (!ref)
+            return undefined;
+        // Check TTL
+        if (this.isExpired(ref)) {
+            this.removeFromCache(elementId);
+            return undefined;
+        }
+        // Update LRU order
+        this.updateAccessOrder(elementId);
+        return ref;
+    }
+    /**
+     * Create element ID mapping with transitive update
+     *
+     * When we map oldId → newId, we also update any existing mappings
+     * that point to oldId to instead point to newId.
+     *
+     * Example:
+     *   Existing: abc → efg
+     *   New mapping: efg → hij
+     *   Result: abc → hij, efg → hij
+     */
+    setMapping(oldId, newId) {
+        // Step 1: Find all mappings where value == oldId (using reverse index)
+        const pointingToOld = this.reverseIndex.get(oldId);
+        if (pointingToOld) {
+            // Update all these mappings to point to newId
+            for (const sourceId of pointingToOld) {
+                this.idMappings.set(sourceId, newId);
+                // Update reverse index
+                this.addToReverseIndex(sourceId, newId);
+            }
+            // Remove old reverse index entry
+            this.reverseIndex.delete(oldId);
+        }
+        // Step 2: Add the new mapping
+        this.idMappings.set(oldId, newId);
+        this.addToReverseIndex(oldId, newId);
+        log.debug(`[UIWatchers] Created element ID mapping: ${oldId} → ${newId}`);
+    }
+    /**
+     * Get mapped element ID if exists
+     * Returns the new ID if a mapping exists, otherwise returns undefined
+     */
+    getMappedId(elementId) {
+        return this.idMappings.get(elementId);
+    }
+    /**
+     * Remove expired entries from cache
+     */
+    cleanup() {
+        const now = Date.now();
+        const toRemove = [];
+        for (const [elementId, ref] of this.cache) {
+            if (now - ref.createdAt >= this.config.elementTtlMs) {
+                toRemove.push(elementId);
+            }
+        }
+        for (const elementId of toRemove) {
+            this.removeFromCache(elementId);
+        }
+        if (toRemove.length > 0) {
+            log.debug(`[UIWatchers] Cleaned up ${toRemove.length} expired cache entries`);
+        }
+    }
+    /**
+     * Clear all cache entries and mappings
+     */
+    clear() {
+        const count = this.cache.size;
+        this.cache.clear();
+        this.idMappings.clear();
+        this.reverseIndex.clear();
+        this.accessOrder = [];
+        log.debug(`[UIWatchers] Cleared element cache (${count} entries)`);
+    }
+    /**
+     * Get current cache size
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get current mappings count
+     */
+    get mappingsCount() {
+        return this.idMappings.size;
+    }
+    // ============================================================================
+    // Private helper methods
+    // ============================================================================
+    addToCache(elementId, ref) {
+        // Evict if at capacity
+        while (this.cache.size >= this.config.maxCacheEntries) {
+            this.evictLRU();
+        }
+        this.cache.set(elementId, ref);
+        this.updateAccessOrder(elementId);
+    }
+    removeFromCache(elementId) {
+        this.cache.delete(elementId);
+        // Remove from access order
+        const index = this.accessOrder.indexOf(elementId);
+        if (index !== -1) {
+            this.accessOrder.splice(index, 1);
+        }
+    }
+    evictLRU() {
+        if (this.accessOrder.length === 0)
+            return;
+        // Remove least recently used (first in array)
+        const lruId = this.accessOrder.shift();
+        if (lruId) {
+            this.cache.delete(lruId);
+            log.debug(`[UIWatchers] Evicted LRU cache entry: ${lruId}`);
+        }
+    }
+    updateAccessOrder(elementId) {
+        // Remove from current position
+        const index = this.accessOrder.indexOf(elementId);
+        if (index !== -1) {
+            this.accessOrder.splice(index, 1);
+        }
+        // Add to end (most recently used)
+        this.accessOrder.push(elementId);
+    }
+    isExpired(ref) {
+        return Date.now() - ref.createdAt >= this.config.elementTtlMs;
+    }
+    addToReverseIndex(oldId, newId) {
+        if (!this.reverseIndex.has(newId)) {
+            this.reverseIndex.set(newId, new Set());
+        }
+        this.reverseIndex.get(newId).add(oldId);
+    }
+}
+//# sourceMappingURL=element-cache.js.map

package/lib/element-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-cache.js","sourceRoot":"","sources":["../src/element-cache.ts"],"names":[],"mappings":"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"}