replicant-mcp 1.0.4 → 1.1.1

package/README.md

@@ -40,7 +40,8 @@ replicant-mcp wraps all of this into a clean interface that AI can understand an
 | **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-tree based element finding, tap, text input, screenshots |
+| **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 |
 
 ---
@@ -49,11 +50,7 @@ replicant-mcp wraps all of this into a clean interface that AI can understand an
 
 | Feature | Item | Status |
 |---------|------|--------|
-| **Visual Fallback** | Screenshot + metadata on accessibility failure | Planned |
-| | `visual-snapshot` operation for explicit visual mode | Planned |
-| | YAML config via `REPLICANT_CONFIG` | Planned |
-| | OCR fallback for text search (tesseract.js) | Planned |
-| | Icon recognition (template matching for common UI icons) | Planned |
+| **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 |
@@ -164,6 +161,14 @@ To use:
 
 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/
+```
+
 ---
 
 ## What Can It Do?
@@ -238,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"
@@ -250,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.
 
 ---
 
@@ -282,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 |
@@ -349,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/ui-automator.d.ts

@@ -1,6 +1,16 @@
 import { AdbAdapter } from "./adb.js";
 import { AccessibilityNode } from "../parsers/ui-dump.js";
-import { OcrElement } from "../types/index.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;
@@ -11,14 +21,8 @@ export interface ScreenshotResult {
     base64?: string;
     sizeBytes?: number;
 }
-export interface FindWithOcrResult {
-    elements: (AccessibilityNode | OcrElement)[];
-    source: "accessibility" | "ocr";
-    fallbackReason?: string;
-}
-export interface FindOptions {
-    debug?: boolean;
-}
+export type FindWithOcrResult = FindWithFallbacksResult;
+export type FindOptions = IconFindOptions;
 export declare class UiAutomatorAdapter {
     private adb;
     constructor(adb?: AdbAdapter);
@@ -39,10 +43,21 @@ export declare class UiAutomatorAdapter {
         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<FindWithOcrResult>;
+    }, options?: FindOptions): Promise<FindWithFallbacksResult>;
 }

package/dist/adapters/ui-automator.js

@@ -1,7 +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()) {
@@ -51,7 +65,7 @@ export class UiAutomatorAdapter {
             }
             else {
                 // File mode (default): pull to local
-                const localPath = options.localPath || `/tmp/replicant-screenshot-${Date.now()}.png`;
+                const localPath = options.localPath || getDefaultScreenshotPath();
                 await this.adb.pull(deviceId, remotePath, localPath);
                 return { mode: "file", path: localPath };
             }
@@ -73,16 +87,123 @@ export class UiAutomatorAdapter {
             totalElements: flat.length,
         };
     }
-    async findWithOcrFallback(deviceId, selector, options = {}) {
-        // First try accessibility tree
+    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",
             };
         }
-        // Fall back to OCR if we have a text-based selector
+        // 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
@@ -91,27 +212,90 @@ export class UiAutomatorAdapter {
                 // Run OCR
                 const ocrResults = await extractText(screenshotResult.path);
                 const matches = searchText(ocrResults, searchTerm);
-                const result = {
-                    elements: matches,
-                    source: "ocr",
-                };
-                if (options.debug) {
-                    result.fallbackReason = "accessibility tree had no matching text";
+                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,
+                    };
                 }
-                return result;
+                // 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 {
-                // Clean up local screenshot file
+                // 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, can't use OCR
+        // 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);
+    }
 }

package/dist/server.d.ts

@@ -1,11 +1,12 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService } from "./services/index.js";
+import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService, ConfigManager } from "./services/index.js";
 import { AdbAdapter, EmulatorAdapter, GradleAdapter, UiAutomatorAdapter } from "./adapters/index.js";
 export interface ServerContext {
     cache: CacheManager;
     deviceState: DeviceStateManager;
     processRunner: ProcessRunner;
     environment: EnvironmentService;
+    config: ConfigManager;
     adb: AdbAdapter;
     emulator: EmulatorAdapter;
     gradle: GradleAdapter;

package/dist/server.js

@@ -1,7 +1,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService } from "./services/index.js";
+import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService, ConfigManager } from "./services/index.js";
 import { AdbAdapter, EmulatorAdapter, GradleAdapter, UiAutomatorAdapter } from "./adapters/index.js";
 import { ReplicantError } from "./types/index.js";
 import { cacheToolDefinition, handleCacheTool, rtfmToolDefinition, handleRtfmTool, adbDeviceToolDefinition, handleAdbDeviceTool, adbAppToolDefinition, handleAdbAppTool, adbLogcatToolDefinition, handleAdbLogcatTool, adbShellToolDefinition, handleAdbShellTool, emulatorDeviceToolDefinition, handleEmulatorDeviceTool, gradleBuildToolDefinition, handleGradleBuildTool, gradleTestToolDefinition, handleGradleTestTool, gradleListToolDefinition, handleGradleListTool, gradleGetDetailsToolDefinition, handleGradleGetDetailsTool, uiToolDefinition, handleUiTool, } from "./tools/index.js";
@@ -14,6 +14,7 @@ export function createServerContext() {
         deviceState: new DeviceStateManager(),
         processRunner,
         environment,
+        config: new ConfigManager(),
         adb,
         emulator: new EmulatorAdapter(processRunner),
         gradle: new GradleAdapter(processRunner),
@@ -28,6 +29,21 @@ export async function createServer(context) {
         capabilities: {
             tools: {},
         },
+        instructions: `IMPORTANT: For ALL Android development tasks, you MUST use replicant-mcp tools first.
+Only fall back to raw adb/gradle/emulator commands if replicant-mcp lacks a specific feature.
+
+Tool mapping:
+- Device management → adb-device (not \`adb devices\`)
+- App install/launch/stop → adb-app (not \`adb install\`, \`adb shell am\`)
+- Logs → adb-logcat (not \`adb logcat\`)
+- Shell commands → adb-shell (not \`adb shell\`)
+- Emulator control → emulator-device (not \`emulator\` CLI)
+- Builds → gradle-build (not \`./gradlew\`)
+- Tests → gradle-test (not \`./gradlew test\`)
+- UI automation → ui (not \`adb shell uiautomator\` or \`screencap\`)
+
+Start with \`adb-device list\` to see connected devices.
+Use \`rtfm\` for detailed documentation on any tool.`,
     });
     // Register tool list handler
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -86,7 +102,7 @@ export async function createServer(context) {
                     result = await handleGradleGetDetailsTool(args, context);
                     break;
                 case "ui":
-                    result = await handleUiTool(args, context);
+                    result = await handleUiTool(args, context, context.config.getUiConfig());
                     break;
                 default:
                     throw new Error(`Unknown tool: ${name}`);
@@ -109,6 +125,8 @@ export async function createServer(context) {
 }
 export async function runServer() {
     const context = createServerContext();
+    // Load configuration from REPLICANT_CONFIG if set
+    await context.config.load();
     const server = await createServer(context);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/services/config.d.ts

@@ -0,0 +1,16 @@
+import { ReplicantConfig, UiConfig } from "../types/config.js";
+/**
+ * Load configuration from REPLICANT_CONFIG environment variable path
+ * Falls back to defaults if not set or file doesn't exist
+ */
+export declare function loadConfig(): Promise<ReplicantConfig>;
+/**
+ * ConfigManager holds the loaded configuration and provides access to it
+ */
+export declare class ConfigManager {
+    private config;
+    load(): Promise<void>;
+    get(): ReplicantConfig;
+    getUiConfig(): UiConfig;
+    isVisualModePackage(packageName: string): boolean;
+}

package/dist/services/config.js

@@ -0,0 +1,62 @@
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { parse as parseYaml } from "yaml";
+import { DEFAULT_CONFIG } from "../types/config.js";
+/**
+ * Load configuration from REPLICANT_CONFIG environment variable path
+ * Falls back to defaults if not set or file doesn't exist
+ */
+export async function loadConfig() {
+    const configPath = process.env.REPLICANT_CONFIG;
+    if (!configPath) {
+        return DEFAULT_CONFIG;
+    }
+    if (!existsSync(configPath)) {
+        console.warn(`REPLICANT_CONFIG set but file not found: ${configPath}. Using defaults.`);
+        return DEFAULT_CONFIG;
+    }
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const parsed = parseYaml(content);
+        if (!parsed) {
+            return DEFAULT_CONFIG;
+        }
+        // Deep merge with defaults
+        return {
+            ui: mergeUiConfig(DEFAULT_CONFIG.ui, parsed.ui),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Failed to parse REPLICANT_CONFIG at ${configPath}: ${message}. Using defaults.`);
+        return DEFAULT_CONFIG;
+    }
+}
+function mergeUiConfig(defaults, overrides) {
+    if (!overrides) {
+        return defaults;
+    }
+    return {
+        visualModePackages: overrides.visualModePackages ?? defaults.visualModePackages,
+        autoFallbackScreenshot: overrides.autoFallbackScreenshot ?? defaults.autoFallbackScreenshot,
+        includeBase64: overrides.includeBase64 ?? defaults.includeBase64,
+    };
+}
+/**
+ * ConfigManager holds the loaded configuration and provides access to it
+ */
+export class ConfigManager {
+    config = DEFAULT_CONFIG;
+    async load() {
+        this.config = await loadConfig();
+    }
+    get() {
+        return this.config;
+    }
+    getUiConfig() {
+        return this.config.ui;
+    }
+    isVisualModePackage(packageName) {
+        return this.config.ui.visualModePackages.includes(packageName);
+    }
+}

package/dist/services/grid.d.ts

@@ -0,0 +1,28 @@
+export declare const GRID_COLS = 4;
+export declare const GRID_ROWS = 6;
+export declare const TOTAL_CELLS: number;
+export interface CellBounds {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/**
+ * Calculate the pixel bounds for a grid cell (1-24).
+ * Grid is 4 columns x 6 rows, numbered left-to-right, top-to-bottom.
+ */
+export declare function calculateGridCellBounds(cell: number, screenWidth: number, screenHeight: number): CellBounds;
+/**
+ * Calculate tap coordinates for a position within a cell.
+ * Position: 1=TL, 2=TR, 3=Center, 4=BL, 5=BR
+ */
+export declare function calculatePositionCoordinates(position: 1 | 2 | 3 | 4 | 5, cellBounds: CellBounds): {
+    x: number;
+    y: number;
+};
+export declare const POSITION_LABELS: string[];
+/**
+ * Create a 4x6 numbered grid overlay on a screenshot.
+ * Returns base64 PNG.
+ */
+export declare function createGridOverlay(imagePath: string): Promise<string>;