replicant-mcp 1.0.0 → 1.1.0

package/README.md

@@ -10,6 +10,12 @@ replicant-mcp is a [Model Context Protocol](https://modelcontextprotocol.io/) se
 
 ---
 
+## Demo
+
+![replicant-mcp demo](demo.gif)
+
+---
+
 ## Why replicant-mcp?
 
 Android development involves juggling a lot: Gradle builds, emulator management, ADB commands, logcat filtering, UI testing. Each has its own CLI, flags, and quirks.
@@ -25,6 +31,41 @@ replicant-mcp wraps all of this into a clean interface that AI can understand an
 
 ---
 
+## Current Features
+
+| Category | Capabilities |
+|----------|-------------|
+| **Build & Test** | Build APKs/bundles, run unit and instrumented tests, list modules/variants/tasks, fetch detailed build logs |
+| **Emulator** | Create, start, stop, wipe emulators; save/load/delete snapshots |
+| **Device Control** | List connected devices, select active device, query device properties |
+| **App Management** | Install, uninstall, launch, stop apps; clear app data; list installed packages |
+| **Log Analysis** | Filter logcat by package, tag, level, time; configurable line limits |
+| **UI Automation** | Accessibility-first element finding with multi-tier fallback (accessibility → OCR → visual), spatial proximity search (`nearestTo`), grid-based precision tapping, tap, text input, screenshots |
+| **Configuration** | YAML config via `REPLICANT_CONFIG` for UI behavior customization |
+| **Utilities** | Response caching with progressive disclosure, on-demand documentation |
+
+---
+
+## Future Roadmap
+
+| Feature | Item | Status |
+|---------|------|--------|
+| **Visual Fallback** | Icon recognition (pattern + visual + grid fallback) | ✅ |
+| | Semantic image search (LLM-assisted visual understanding) | Future |
+| **Custom Build Commands** | Skill override for project-specific builds | Planned |
+| | Auto-detect gradlew vs gradle | Planned |
+| | Configurable default variant | Planned |
+| | Extend skill override to test/lint operations | Future |
+| **Video Capture** | Start/stop recording | Planned |
+| | Duration-based capture | Planned |
+| | Configurable output directory and quality | Planned |
+| | WebM/GIF conversion (ffmpeg) | Future |
+| **Developer Experience** | Simplified tool authoring with `defineTool()` helper | Future |
+| | Auto-generate JSON schema from Zod via `zod-to-json-schema` | Future |
+| | Convention-based tool auto-discovery (no manual wiring) | Future |
+
+---
+
 ## Quick Start
 
 ### Prerequisites
@@ -43,18 +84,17 @@ emulator -version  # Should show Android emulator version
 
 ### Installation
 
+**Option 1: npm (recommended)**
+```bash
+npm install -g replicant-mcp
+```
+
+**Option 2: From source**
 ```bash
-# Clone the repo
 git clone https://github.com/thecombatwombat/replicant-mcp.git
 cd replicant-mcp
-
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Verify everything works
 npm test
 ```
 
@@ -75,31 +115,59 @@ Add this to your Claude Desktop config (`~/Library/Application Support/Claude/cl
 
 Restart Claude Desktop. You should see "replicant" in the MCP servers list.
 
-### Alternative: Claude Code Skill
+### Connect to Claude Code
 
-If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic's CLI), you can install replicant as a skill instead of an MCP server. This provides shell script wrappers optimized for Claude Code's workflow.
+Add the MCP server with environment variables for Android SDK:
 
-**Option 1: Via Plugin Marketplace (Recommended)**
 ```bash
-/plugin marketplace add thecombatwombat/replicant-mcp
-/plugin install replicant-dev@replicant-mcp
+claude mcp add replicant \
+  -e ANDROID_HOME=$HOME/Library/Android/sdk \
+  -e PATH="$HOME/Library/Android/sdk/platform-tools:$HOME/Library/Android/sdk/emulator:$HOME/Library/Android/sdk/cmdline-tools/latest/bin:$PATH" \
+  -- node $(npm root -g)/replicant-mcp/dist/index.js
 ```
 
-**Option 2: Manual Installation**
-```bash
-# From the replicant-mcp directory
-npm run install-skill
+> **Note:** Adjust `ANDROID_HOME` if your Android SDK is in a different location. On Linux, it's typically `$HOME/Android/Sdk`.
+
+Restart Claude Code to load the MCP server.
+
+### Reducing Permission Prompts (Optional)
+
+By default, Claude Code asks for permission on each tool call. To auto-approve replicant-mcp tools, add this to your `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__replicant__*"
+    ]
+  }
+}
 ```
 
-After installation, restart Claude Code to load the skill. The skill provides the same Android development capabilities through shell scripts rather than MCP tools.
+This is especially useful for agentic workflows where human intervention is limited.
 
-> **Note:** The Claude Code skill is currently compatible with macOS and Linux only. Windows support is planned for a future release.
+### PR Automation (Optional)
 
-**Which should you choose?**
-- **MCP Server** — Use with Claude Desktop or any MCP-compatible client
-- **Claude Code Skill** — Use with Claude Code CLI for a shell-native experience
+This project includes a Claude Code skill for automated PR handling. When invoked, it:
+- Creates a branch and PR from your current changes
+- Polls for Greptile and human reviews every 2 minutes (max 5 cycles)
+- Automatically addresses Greptile feedback
+- Merges when a human approves
 
-Both approaches provide the same core functionality.
+To use:
+```
+/pr-with-review --branch feature/my-feature --title "My PR" --body "Description" --commit-message "feat: add feature"
+```
+
+Or let Claude invoke it automatically when creating PRs.
+
+### Output Directory
+
+replicant-mcp stores screenshots in `.replicant/screenshots/` within your current working directory. Add this to your `.gitignore`:
+
+```gitignore
+.replicant/
+```
 
 ---
 
@@ -175,7 +243,7 @@ Claude: Let me check the error logs.
         Want me to look at that file?
 ```
 
-### UI Automation (No Screenshots Needed!)
+### UI Automation (Smart Element Finding)
 
 ```
 You: "Tap the Login button"
@@ -187,7 +255,26 @@ Claude: I'll find and tap the Login button.
         Tapped "Login" at coordinates (540, 1847)
 ```
 
-This works by reading the **accessibility tree**—the same data screen readers use. It's faster, cheaper, and more reliable than screenshot-based approaches.
+**Spatial proximity search** — find elements near other elements:
+```
+You: "Tap the edit icon next to John's name"
+
+Claude: [Calls ui with operation: "find", selector: { textContains: "edit", nearestTo: "John" }]
+        Found edit button nearest to "John" at (892, 340)
+```
+
+**Multi-tier fallback** — when accessibility data isn't available:
+1. **Accessibility tree** — fast, reliable, text-based
+2. **OCR fallback** — Tesseract extracts text from screenshot
+3. **Visual fallback** — returns screenshot + metadata for AI vision
+
+**Grid-based precision** — tap icons without text labels:
+```
+Claude: [Calls ui with operation: "tap", gridCell: 5, gridPosition: 3]
+        // Taps center of cell 5 in a 24-cell grid overlay
+```
+
+This approach is faster, cheaper, and more reliable than pure screenshot-based automation.
 
 ---
 
@@ -219,7 +306,7 @@ replicant-mcp provides 12 tools organized into categories:
 ### UI Automation
 | Tool | Description |
 |------|-------------|
-| `ui` | Dump accessibility tree, find elements, tap, input text, screenshot |
+| `ui` | Element finding with fallback chain, spatial search (`nearestTo`), tap (coordinates or grid), input text, screenshot, accessibility-check, visual-snapshot |
 
 ### Utilities
 | Tool | Description |
@@ -286,6 +373,32 @@ The `adb-shell` tool blocks dangerous commands like `rm -rf /`, `reboot`, and `s
 
 ---
 
+## Configuration
+
+replicant-mcp can be configured via a YAML file. Set the `REPLICANT_CONFIG` environment variable to the path:
+
+```bash
+export REPLICANT_CONFIG=/path/to/config.yaml
+```
+
+**Example config.yaml:**
+```yaml
+ui:
+  # Always use visual mode (skip accessibility) for these packages
+  visualModePackages:
+    - com.example.legacy.app
+
+  # Auto-include screenshot when find returns no results (default: true)
+  autoFallbackScreenshot: true
+
+  # Include base64-encoded screenshot in responses (default: false)
+  includeBase64: false
+```
+
+Most users won't need a config file—the defaults work well for typical Android apps.
+
+---
+
 ## Development
 
 ### Project Structure

package/dist/adapters/adb.d.ts

@@ -11,6 +11,7 @@ export declare class AdbAdapter {
     stop(deviceId: string, packageName: string): Promise<void>;
     clearData(deviceId: string, packageName: string): Promise<void>;
     shell(deviceId: string, command: string, timeoutMs?: number): Promise<RunResult>;
+    pull(deviceId: string, remotePath: string, localPath: string): Promise<void>;
     logcat(deviceId: string, options: {
         lines?: number;
         filter?: string;

package/dist/adapters/adb.js

@@ -45,6 +45,12 @@ export class AdbAdapter {
     async shell(deviceId, command, timeoutMs) {
         return this.adb(["-s", deviceId, "shell", command], timeoutMs);
     }
+    async pull(deviceId, remotePath, localPath) {
+        const result = await this.adb(["-s", deviceId, "pull", remotePath, localPath]);
+        if (result.exitCode !== 0) {
+            throw new ReplicantError(ErrorCode.PULL_FAILED, `Failed to pull ${remotePath} to ${localPath}`, result.stderr || "Check device connection and file paths");
+        }
+    }
     async logcat(deviceId, options) {
         const args = ["-s", deviceId, "logcat", "-d"];
         if (options.lines) {
@@ -70,6 +76,6 @@ export class AdbAdapter {
         return props;
     }
     async adb(args, timeoutMs) {
-        return this.runner.run("adb", args, { timeoutMs });
+        return this.runner.runAdb(args, { timeoutMs });
     }
 }

package/dist/adapters/emulator.js

@@ -8,8 +8,8 @@ export class EmulatorAdapter {
     }
     async list() {
         const [avdResult, runningResult] = await Promise.all([
-            this.runner.run("avdmanager", ["list", "avd"]),
-            this.runner.run("emulator", ["-list-avds"]),
+            this.runner.runAvdManager(["list", "avd"]),
+            this.runner.runEmulator(["-list-avds"]),
         ]);
         return {
             available: parseAvdList(avdResult.stdout),
@@ -17,7 +17,7 @@ export class EmulatorAdapter {
         };
     }
     async create(name, device, systemImage) {
-        const result = await this.runner.run("avdmanager", [
+        const result = await this.runner.runAvdManager([
             "create", "avd",
             "-n", name,
             "-k", systemImage,
@@ -31,7 +31,7 @@ export class EmulatorAdapter {
     async start(avdName) {
         // Start emulator in background - don't wait for it
         // Returns immediately, emulator boots in background
-        this.runner.run("emulator", [
+        this.runner.runEmulator([
             "-avd", avdName,
             "-no-snapshot-load",
             "-no-boot-anim",
@@ -41,7 +41,7 @@ export class EmulatorAdapter {
         // Give it a moment to register
         await new Promise((r) => setTimeout(r, 2000));
         // Find the new emulator ID
-        const result = await this.runner.run("adb", ["devices"]);
+        const result = await this.runner.runAdb(["devices"]);
         const match = result.stdout.match(/emulator-\d+/);
         if (!match) {
             throw new ReplicantError(ErrorCode.EMULATOR_START_FAILED, `Emulator ${avdName} failed to start`, "Check the AVD name and try again");
@@ -49,24 +49,24 @@ export class EmulatorAdapter {
         return match[0];
     }
     async kill(emulatorId) {
-        await this.runner.run("adb", ["-s", emulatorId, "emu", "kill"]);
+        await this.runner.runAdb(["-s", emulatorId, "emu", "kill"]);
     }
     async wipe(avdName) {
-        await this.runner.run("emulator", ["-avd", avdName, "-wipe-data", "-no-window"], { timeoutMs: 5000 }).catch(() => {
+        await this.runner.runEmulator(["-avd", avdName, "-wipe-data", "-no-window"], { timeoutMs: 5000 }).catch(() => {
             // Expected behavior
         });
     }
     async snapshotSave(emulatorId, name) {
-        await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "save", name]);
+        await this.runner.runAdb(["-s", emulatorId, "emu", "avd", "snapshot", "save", name]);
     }
     async snapshotLoad(emulatorId, name) {
-        await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "load", name]);
+        await this.runner.runAdb(["-s", emulatorId, "emu", "avd", "snapshot", "load", name]);
     }
     async snapshotList(emulatorId) {
-        const result = await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "list"]);
+        const result = await this.runner.runAdb(["-s", emulatorId, "emu", "avd", "snapshot", "list"]);
         return parseSnapshotList(result.stdout);
     }
     async snapshotDelete(emulatorId, name) {
-        await this.runner.run("adb", ["-s", emulatorId, "emu", "avd", "snapshot", "delete", name]);
+        await this.runner.runAdb(["-s", emulatorId, "emu", "avd", "snapshot", "delete", name]);
     }
 }

package/dist/adapters/ui-automator.d.ts

@@ -1,5 +1,28 @@
 import { AdbAdapter } from "./adb.js";
 import { AccessibilityNode } from "../parsers/ui-dump.js";
+import { VisualSnapshot } from "../types/index.js";
+import { FindWithFallbacksResult, FindOptions as IconFindOptions } from "../types/icon-recognition.js";
+export interface ScreenMetadata {
+    width: number;
+    height: number;
+    density: number;
+}
+export interface CurrentApp {
+    packageName: string;
+    activityName: string;
+}
+export interface ScreenshotOptions {
+    localPath?: string;
+    inline?: boolean;
+}
+export interface ScreenshotResult {
+    mode: "file" | "inline";
+    path?: string;
+    base64?: string;
+    sizeBytes?: number;
+}
+export type FindWithOcrResult = FindWithFallbacksResult;
+export type FindOptions = IconFindOptions;
 export declare class UiAutomatorAdapter {
     private adb;
     constructor(adb?: AdbAdapter);
@@ -13,11 +36,28 @@ export declare class UiAutomatorAdapter {
     tap(deviceId: string, x: number, y: number): Promise<void>;
     tapElement(deviceId: string, element: AccessibilityNode): Promise<void>;
     input(deviceId: string, text: string): Promise<void>;
-    screenshot(deviceId: string, localPath: string): Promise<void>;
+    screenshot(deviceId: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
     accessibilityCheck(deviceId: string): Promise<{
         hasAccessibleElements: boolean;
         clickableCount: number;
         textCount: number;
         totalElements: number;
     }>;
+    getScreenMetadata(deviceId: string): Promise<ScreenMetadata>;
+    getCurrentApp(deviceId: string): Promise<CurrentApp>;
+    visualSnapshot(deviceId: string, options?: {
+        includeBase64?: boolean;
+    }): Promise<VisualSnapshot>;
+    findWithFallbacks(deviceId: string, selector: {
+        resourceId?: string;
+        text?: string;
+        textContains?: string;
+        className?: string;
+    }, options?: FindOptions): Promise<FindWithFallbacksResult>;
+    findWithOcrFallback(deviceId: string, selector: {
+        resourceId?: string;
+        text?: string;
+        textContains?: string;
+        className?: string;
+    }, options?: FindOptions): Promise<FindWithFallbacksResult>;
 }

package/dist/adapters/ui-automator.js

@@ -1,5 +1,21 @@
+import * as path from "path";
+import * as fs from "fs";
 import { AdbAdapter } from "./adb.js";
 import { parseUiDump, findElements, flattenTree } from "../parsers/ui-dump.js";
+import { ReplicantError, ErrorCode } from "../types/index.js";
+import { extractText, searchText } from "../services/ocr.js";
+import { matchIconPattern, matchesResourceId } from "../services/icon-patterns.js";
+import { filterIconCandidates, formatBounds, cropCandidateImage } from "../services/visual-candidates.js";
+import { calculateGridCellBounds, calculatePositionCoordinates, createGridOverlay, POSITION_LABELS, } from "../services/grid.js";
+/**
+ * Get default screenshot path in project-relative .replicant/screenshots directory.
+ * Creates the directory if it doesn't exist.
+ */
+function getDefaultScreenshotPath() {
+    const dir = path.join(process.cwd(), ".replicant", "screenshots");
+    fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, `screenshot-${Date.now()}.png`);
+}
 export class UiAutomatorAdapter {
     adb;
     constructor(adb = new AdbAdapter()) {
@@ -29,14 +45,35 @@ export class UiAutomatorAdapter {
         const escaped = text.replace(/(['"\\$`])/g, "\\$1").replace(/ /g, "%s");
         await this.adb.shell(deviceId, `input text "${escaped}"`);
     }
-    async screenshot(deviceId, localPath) {
-        const remotePath = "/sdcard/screenshot.png";
-        await this.adb.shell(deviceId, `screencap -p ${remotePath}`);
-        // Pull to local (using adb pull via shell workaround)
-        // In real implementation, would use adb pull directly
-        const result = await this.adb.shell(deviceId, `base64 ${remotePath}`);
-        // For now, just verify it worked
-        await this.adb.shell(deviceId, `rm ${remotePath}`);
+    async screenshot(deviceId, options = {}) {
+        const remotePath = "/sdcard/replicant-screenshot.png";
+        // Capture screenshot on device
+        const captureResult = await this.adb.shell(deviceId, `screencap -p ${remotePath}`);
+        if (captureResult.exitCode !== 0) {
+            throw new ReplicantError(ErrorCode.SCREENSHOT_FAILED, "Failed to capture screenshot", captureResult.stderr || "Ensure device screen is on and unlocked");
+        }
+        try {
+            if (options.inline) {
+                // Inline mode: return base64
+                const base64Result = await this.adb.shell(deviceId, `base64 ${remotePath}`);
+                const sizeResult = await this.adb.shell(deviceId, `stat -c%s ${remotePath}`);
+                return {
+                    mode: "inline",
+                    base64: base64Result.stdout.trim(),
+                    sizeBytes: parseInt(sizeResult.stdout.trim(), 10),
+                };
+            }
+            else {
+                // File mode (default): pull to local
+                const localPath = options.localPath || getDefaultScreenshotPath();
+                await this.adb.pull(deviceId, remotePath, localPath);
+                return { mode: "file", path: localPath };
+            }
+        }
+        finally {
+            // Always clean up remote file
+            await this.adb.shell(deviceId, `rm -f ${remotePath}`);
+        }
     }
     async accessibilityCheck(deviceId) {
         const tree = await this.dump(deviceId);
@@ -50,4 +87,215 @@ export class UiAutomatorAdapter {
             totalElements: flat.length,
         };
     }
+    async getScreenMetadata(deviceId) {
+        // Get screen size via wm size
+        const sizeResult = await this.adb.shell(deviceId, "wm size");
+        const sizeMatch = sizeResult.stdout.match(/Physical size:\s*(\d+)x(\d+)/);
+        let width = 1080;
+        let height = 1920;
+        if (sizeMatch) {
+            width = parseInt(sizeMatch[1], 10);
+            height = parseInt(sizeMatch[2], 10);
+        }
+        // Get density via wm density
+        const densityResult = await this.adb.shell(deviceId, "wm density");
+        const densityMatch = densityResult.stdout.match(/Physical density:\s*(\d+)/);
+        // Convert DPI to density multiplier (baseline is 160 dpi)
+        let density = 2.75; // Default reasonable value
+        if (densityMatch) {
+            const dpi = parseInt(densityMatch[1], 10);
+            density = dpi / 160;
+        }
+        return { width, height, density };
+    }
+    async getCurrentApp(deviceId) {
+        // Get current focused activity
+        const result = await this.adb.shell(deviceId, "dumpsys activity activities | grep mResumedActivity");
+        // Parse: mResumedActivity: ActivityRecord{... com.example/.MainActivity t123}
+        const match = result.stdout.match(/([a-zA-Z0-9_.]+)\/([a-zA-Z0-9_.]+)\s+/);
+        if (match) {
+            return {
+                packageName: match[1],
+                activityName: match[2],
+            };
+        }
+        // Fallback to simpler approach
+        const fallbackResult = await this.adb.shell(deviceId, "dumpsys window | grep mCurrentFocus");
+        const fallbackMatch = fallbackResult.stdout.match(/([a-zA-Z0-9_.]+)\/([a-zA-Z0-9_.]+)/);
+        if (fallbackMatch) {
+            return {
+                packageName: fallbackMatch[1],
+                activityName: fallbackMatch[2],
+            };
+        }
+        return {
+            packageName: "unknown",
+            activityName: "unknown",
+        };
+    }
+    async visualSnapshot(deviceId, options = {}) {
+        // Always get file-based screenshot first
+        const [screenshotResult, screen, app] = await Promise.all([
+            this.screenshot(deviceId, {}),
+            this.getScreenMetadata(deviceId),
+            this.getCurrentApp(deviceId),
+        ]);
+        const snapshot = {
+            screenshotPath: screenshotResult.path,
+            screen,
+            app,
+        };
+        // Optionally also get base64 encoding from local file
+        if (options.includeBase64 && screenshotResult.path) {
+            const fs = await import("fs/promises");
+            const buffer = await fs.readFile(screenshotResult.path);
+            snapshot.screenshotBase64 = buffer.toString("base64");
+        }
+        return snapshot;
+    }
+    async findWithFallbacks(deviceId, selector, options = {}) {
+        // Handle Tier 5 grid refinement FIRST (when gridCell and gridPosition are provided)
+        if (options.gridCell !== undefined && options.gridPosition !== undefined) {
+            const screen = await this.getScreenMetadata(deviceId);
+            const cellBounds = calculateGridCellBounds(options.gridCell, screen.width, screen.height);
+            const coords = calculatePositionCoordinates(options.gridPosition, cellBounds);
+            return {
+                elements: [
+                    {
+                        index: 0,
+                        bounds: `[${cellBounds.x0},${cellBounds.y0}][${cellBounds.x1},${cellBounds.y1}]`,
+                        center: coords,
+                    },
+                ],
+                source: "grid",
+                tier: 5,
+                confidence: "low",
+            };
+        }
+        // Tier 1: Accessibility text match
+        const accessibilityResults = await this.find(deviceId, selector);
+        if (accessibilityResults.length > 0) {
+            return {
+                elements: accessibilityResults,
+                source: "accessibility",
+                tier: 1,
+                confidence: "high",
+            };
+        }
+        // Tier 2: ResourceId pattern match (for text-based queries)
+        if (selector.text || selector.textContains) {
+            const query = selector.text || selector.textContains;
+            const patterns = matchIconPattern(query);
+            if (patterns) {
+                const tree = await this.dump(deviceId);
+                const flat = flattenTree(tree);
+                const patternMatches = flat.filter((node) => node.resourceId && matchesResourceId(node.resourceId, patterns));
+                if (patternMatches.length > 0) {
+                    return {
+                        elements: patternMatches,
+                        source: "accessibility",
+                        tier: 2,
+                        confidence: "high",
+                        fallbackReason: options.debug
+                            ? "no text match, found via resourceId pattern"
+                            : undefined,
+                    };
+                }
+            }
+        }
+        // Tier 3: OCR (existing logic)
+        if (selector.text || selector.textContains) {
+            const searchTerm = selector.text || selector.textContains;
+            // Take screenshot for OCR
+            const screenshotResult = await this.screenshot(deviceId, {});
+            try {
+                // Run OCR
+                const ocrResults = await extractText(screenshotResult.path);
+                const matches = searchText(ocrResults, searchTerm);
+                if (matches.length > 0) {
+                    return {
+                        elements: matches,
+                        source: "ocr",
+                        tier: 3,
+                        confidence: "high",
+                        fallbackReason: options.debug
+                            ? "no accessibility or pattern match, found via OCR"
+                            : undefined,
+                    };
+                }
+                // Tier 4: Visual candidates (unlabeled clickables)
+                const tree = await this.dump(deviceId);
+                const flat = flattenTree(tree);
+                const iconCandidates = filterIconCandidates(flat);
+                if (iconCandidates.length > 0) {
+                    const candidates = await Promise.all(iconCandidates.map(async (node, index) => ({
+                        index,
+                        bounds: formatBounds(node),
+                        center: { x: node.centerX, y: node.centerY },
+                        image: await cropCandidateImage(screenshotResult.path, node.bounds),
+                    })));
+                    const allUnlabeled = flat.filter((n) => n.clickable && !n.text && !n.contentDesc);
+                    return {
+                        elements: [],
+                        source: "visual",
+                        tier: 4,
+                        confidence: "medium",
+                        candidates,
+                        truncated: iconCandidates.length < allUnlabeled.length,
+                        totalCandidates: allUnlabeled.length,
+                        fallbackReason: options.debug
+                            ? "no text/pattern/OCR match, showing visual candidates"
+                            : undefined,
+                    };
+                }
+                // Tier 5: Grid fallback (empty or unusable accessibility tree)
+                const screen = await this.getScreenMetadata(deviceId);
+                const gridImage = await createGridOverlay(screenshotResult.path);
+                return {
+                    elements: [],
+                    source: "grid",
+                    tier: 5,
+                    confidence: "low",
+                    gridImage,
+                    gridPositions: POSITION_LABELS,
+                    fallbackReason: options.debug
+                        ? "no usable elements, showing grid for coordinate selection"
+                        : undefined,
+                };
+            }
+            finally {
+                // Always clean up screenshot - Tier 3/4/5 all embed base64 data in response
+                if (screenshotResult.path) {
+                    const fs = await import("fs/promises");
+                    await fs.unlink(screenshotResult.path).catch(() => { });
+                }
+            }
+        }
+        // No text selector - return empty with visual fallback if requested
+        if (options.includeVisualFallback) {
+            const snapshot = await this.visualSnapshot(deviceId, {
+                includeBase64: options.includeBase64,
+            });
+            return {
+                elements: [],
+                source: "accessibility",
+                tier: 1,
+                confidence: "high",
+                visualFallback: {
+                    ...snapshot,
+                    hint: "No elements matched selector. Use screenshot to identify tap coordinates.",
+                },
+            };
+        }
+        return {
+            elements: [],
+            source: "accessibility",
+            tier: 1,
+            confidence: "high",
+        };
+    }
+    // Backward compatible alias
+    async findWithOcrFallback(deviceId, selector, options = {}) {
+        return this.findWithFallbacks(deviceId, selector, options);
+    }
 }