react-native-ai-devtools 1.4.18 → 1.4.20

package/build/index.js

@@ -17,7 +17,7 @@ import { logBuffers, networkBuffers, getLogBuffer, getNetworkBuffer, getTotalLog
 // React Component Inspection
 getComponentTree, getScreenLayout, inspectComponent, findComponents, inspectAtPoint, toggleElementInspector, isInspectorActive, getInspectorSelection, getFirstConnectedApp, getLogs, searchLogs, getLogSummary, getNetworkRequests, searchNetworkRequests, getNetworkStats, formatRequestDetails, 
 // Connection state
-getAllConnectionStates, getAllConnectionMetadata, getRecentGaps, formatDuration, cancelAllReconnectionTimers, cancelReconnectionTimer, clearAllConnectionState, clearAllCDPMessageTimes, suppressReconnection, suppressReconnectionForKey, clearReconnectionSuppression, 
+getAllConnectionStates, getAllConnectionMetadata, getRecentGaps, formatDuration, cancelAllReconnectionTimers, cancelReconnectionTimer, clearAllConnectionState, clearAllCDPMessageTimes, suppressReconnection, suppressReconnectionForKey, clearReconnectionSuppression, purgeStaleConnectionsForPorts, 
 // Context health tracking
 getContextHealth, 
 // Connection resilience
@@ -27,7 +27,7 @@ connectMetroBuildEvents, disconnectMetroBuildEvents, getBundleErrors, getBundleS
 // Error screen parsing (OCR fallback)
 parseErrorScreenText, formatParsedError, 
 // OCR
-recognizeText, inferIOSDevicePixelRatio, 
+recognizeText, inferIOSDevicePixelRatio, enrichScreenshotWithLayout, 
 // Android
 listAndroidDevices, androidScreenshot, androidInstallApp, androidLaunchApp, androidListPackages, 
 // Android UI Input (Phase 2)
@@ -42,8 +42,6 @@ listIOSSimulators, iosScreenshot, iosInstallApp, iosLaunchApp, iosOpenUrl, iosTe
 iosTap, iosSwipe, iosInputText, iosButton, iosKeyEvent, iosKeySequence, iosDescribeAll, iosDescribePoint, IOS_BUTTON_TYPES, 
 // iOS Element Finding (no screenshots)
 iosFindElement, iosWaitForElement, 
-// Debug HTTP Server
-startDebugHttpServer, getDebugServerPort, 
 // Telemetry
 initTelemetry, trackToolInvocation, getTargetPlatform, 
 // Format utilities (TONL)
@@ -332,6 +330,10 @@ registerToolWithTelemetry("scan_metro", {
             portDevices.set(port, debuggable);
         }
     }
+    // Phase 1.5: Purge stale connections for scanned ports
+    // When Metro restarts with a different app, device IDs change.
+    // Old connections remain in connectedApps — remove them before connecting new devices.
+    const purged = purgeStaleConnectionsForPorts(portDevices);
     // Phase 2: Assign each device to the best port
     // If a device appears on multiple ports, prefer the port where it has
     // the fewest OTHER unique devices (i.e. its dedicated Metro server)
@@ -370,6 +372,9 @@ registerToolWithTelemetry("scan_metro", {
     }
     // Phase 3: Connect devices to their assigned ports
     const results = [];
+    if (purged.length > 0) {
+        results.push(`Purged ${purged.length} stale connection(s): ${purged.join(", ")}`);
+    }
     for (const port of openPorts) {
         const devices = portDevices.get(port);
         if (!devices) {
@@ -1246,13 +1251,8 @@ registerToolWithTelemetry("inspect_global", {
 // ============================================================================
 // Tool: Get the React component tree
 registerToolWithTelemetry("get_component_tree", {
-    description: "Get the React component tree from the running app. **RECOMMENDED**: Use focusedOnly=true with structureOnly=true for a token-efficient overview of just the active screen (~1-2KB). This skips navigation wrappers and global overlays, showing only what's actually visible.",
+    description: "Get the full React component tree from the running app. Shows the complete fiber hierarchy including providers, navigation wrappers, and internal components. For a screen overview with positions and text, use get_screen_layout instead. Use structureOnly=true for compact names-only output.",
     inputSchema: {
-        focusedOnly: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Return only the focused/active screen subtree, skipping navigation wrappers and overlays. Dramatically reduces output size. (Recommended: true)"),
         structureOnly: z
             .boolean()
             .optional()
@@ -1261,7 +1261,7 @@ registerToolWithTelemetry("get_component_tree", {
         maxDepth: z
             .number()
             .optional()
-            .describe("Maximum tree depth (default: 25 for focusedOnly+structureOnly, 40 for structureOnly, 100 for full mode)"),
+            .describe("Maximum tree depth (default: 5000)"),
         includeProps: z
             .boolean()
             .optional()
@@ -1284,9 +1284,8 @@ registerToolWithTelemetry("get_component_tree", {
             .describe("Output format: 'json' or 'tonl' (default, compact indented tree). Ignored if structureOnly=true."),
         device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ focusedOnly, structureOnly, maxDepth, includeProps, includeStyles, hideInternals, format, device }) => {
+}, async ({ structureOnly, maxDepth, includeProps, includeStyles, hideInternals, format, device }) => {
     const result = await getComponentTree({
-        focusedOnly,
         structureOnly,
         maxDepth,
         includeProps,
@@ -1317,37 +1316,22 @@ registerToolWithTelemetry("get_component_tree", {
 });
 // Tool: Get full screen layout (all components with layout styles)
 registerToolWithTelemetry("get_screen_layout", {
-    description: "Get layout information for all components on screen. **USE AFTER get_component_tree**: First use get_component_tree(structureOnly=true) to understand structure, then use this tool OR find_components with includeLayout=true to get layout details for specific areas. This tool returns full layout data which can be large for complex screens.",
+    description: "Get a screen map showing visible components as an indented tree with actual screen positions. Uses measureInWindow for real coordinates and filters out off-screen components. Returns meaningful component names with text content and frame data (x,y width x height). Coordinates are in **points** (iOS) or **dp** (Android) — NOT screenshot pixels. Use tap(text=...) or tap(testID=...) to interact with discovered components. Use extended=true to include layout styles (padding, margin, flex, backgroundColor, etc.).",
     inputSchema: {
-        maxDepth: z
-            .number()
-            .optional()
-            .default(65)
-            .describe("Maximum tree depth to traverse (default: 65, balanced for most screens)"),
-        componentsOnly: z
+        extended: z
             .boolean()
             .optional()
             .default(false)
-            .describe("Only show custom components, hide host components (View, Text, etc.)"),
-        shortPath: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Show only last 3 path segments instead of full path (default: true)"),
+            .describe("Include layout styles (padding, margin, flex, backgroundColor, borderRadius, etc.) for each component. Default: false for compact output."),
         summary: z
             .boolean()
             .optional()
             .default(false)
-            .describe("Return only component counts by name instead of full element list (default: false)"),
-        format: z
-            .enum(["json", "tonl"])
-            .optional()
-            .default("tonl")
-            .describe("Output format: 'json' or 'tonl' (default, pipe-delimited rows, ~40% smaller)"),
+            .describe("Return only component counts by name instead of full tree (default: false)"),
         device: z.string().optional().describe("Target device name (substring match). Omit for default device. Run get_apps to see connected devices.")
     }
-}, async ({ maxDepth, componentsOnly, shortPath, summary, format, device }) => {
-    const result = await getScreenLayout({ maxDepth, componentsOnly, shortPath, summary, format, device });
+}, async ({ extended, summary, device }) => {
+    const result = await getScreenLayout({ extended, summary, device });
     if (!result.success) {
         return {
             content: [
@@ -1370,7 +1354,7 @@ registerToolWithTelemetry("get_screen_layout", {
 });
 // Tool: Inspect a specific component by name
 registerToolWithTelemetry("inspect_component", {
-    description: "Inspect a specific React component by name. **DRILL-DOWN TOOL**: Use after get_component_tree(structureOnly=true) to inspect specific components. Returns props, style, state (hooks), and optionally children tree. Use childrenDepth to control how deep nested children go.",
+    description: "Inspect a specific React component by name. **DRILL-DOWN TOOL**: Use after get_screen_layout or find_components to identify which component to inspect. Returns props, style, state (hooks), and optionally children tree. Use childrenDepth to control how deep nested children go.",
     inputSchema: {
         componentName: z
             .string()
@@ -1431,7 +1415,7 @@ registerToolWithTelemetry("inspect_component", {
 });
 // Tool: Find components matching a pattern
 registerToolWithTelemetry("find_components", {
-    description: "Find components matching a name pattern. **TARGETED SEARCH**: Use after get_component_tree(structureOnly=true) to find specific components by pattern and get their layout info. More efficient than get_screen_layout for targeted queries. Use includeLayout=true to get padding/margin/flex styles.",
+    description: "Find components matching a name pattern. **TARGETED SEARCH**: Use after get_screen_layout or get_component_tree(structureOnly=true) to find specific components by pattern. Use includeLayout=true to get padding/margin/flex styles.",
     inputSchema: {
         pattern: z
             .string()
@@ -1486,7 +1470,7 @@ registerToolWithTelemetry("tap", {
         "- tap(text=\"Submit\") — finds and taps element with matching text\n" +
         "- tap(testID=\"login-btn\") — finds by testID\n" +
         "- tap(component=\"HamburgerIcon\") — finds by React component name\n" +
-        "- tap(x=300, y=600) — taps at pixel coordinates from screenshot (conversion handled internally)\n" +
+        "- tap(x=300, y=600) — taps at pixel coordinates (LAST RESORT — only use if text/testID/component strategies all fail)\n" +
         "- tap(text=\"Menu\", strategy=\"ocr\") — forces OCR strategy only\n" +
         "- tap(x=300, y=600, native=true, platform=\"android\") — taps directly via ADB/simctl without React Native connection\n\n" +
         "Returns a post-tap screenshot by default (set screenshot=false to disable). " +
@@ -2664,7 +2648,7 @@ registerToolWithTelemetry("list_android_devices", {
 });
 // Tool: Android screenshot
 registerToolWithTelemetry("android_screenshot", {
-    description: "Take a screenshot from an Android device/emulator. Returns the image data that can be displayed.",
+    description: "Take a screenshot from an Android device/emulator. Returns the image and a screen layout overlay showing visible React components with names, text content, hierarchy, and tap-ready pixel coordinates. Use component names for inspect_component/find_components. Use tap(text=...) for interaction — only fall back to tap(x,y) coordinates from the layout if all tap strategies fail.",
     inputSchema: {
         outputPath: z
             .string()
@@ -2721,6 +2705,16 @@ registerToolWithTelemetry("android_screenshot", {
         catch {
             // Use defaults
         }
+        // Enrich with screen layout data (component names + tap coordinates)
+        // Android: density ratio = densityDpi / 160 (160dpi = 1dp = 1px baseline)
+        const androidPixelRatio = densityDpi / 160;
+        let layoutText = null;
+        try {
+            layoutText = await enrichScreenshotWithLayout(androidPixelRatio, result.scaleFactor || 1);
+        }
+        catch {
+            // Non-fatal: screenshot works without layout enrichment
+        }
         infoText += `\n📱 Android uses PIXELS for all coordinates`;
         if (result.scaleFactor && result.scaleFactor > 1) {
             infoText += `\n🖼️ Image was scaled down to fit API limits (scale: ${result.scaleFactor.toFixed(3)})`;
@@ -2731,11 +2725,22 @@ registerToolWithTelemetry("android_screenshot", {
         }
         infoText += `\n⚠️ Status bar: ${statusBarPixels}px (${statusBarDp}dp) from top - app content starts below this`;
         infoText += `\n📊 Display density: ${densityDpi}dpi`;
-        infoText += `\n\n💡 Next steps:`;
-        infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
-        infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
-        infoText += `\n  • android_describe_all — get full UI tree with exact tap coordinates`;
-        infoText += `\n  • android_find_element(text="...") — find element coordinates without tapping`;
+        if (layoutText) {
+            infoText += `\n\n📋 Screen Layout (components with tap coordinates in pixels):`;
+            infoText += `\n${layoutText}`;
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text (preferred)`;
+            infoText += `\n  • tap(testID="id") or tap(component="Name") — tap by testID or component name`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — use tap coordinates from layout above ONLY if text/testID/component tap fails`;
+            infoText += `\n  • inspect_component("ComponentName") — inspect a component from the layout above`;
+        }
+        else {
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
+            infoText += `\n  • android_describe_all — get full UI tree with exact tap coordinates`;
+            infoText += `\n  • android_find_element(text="...") — find element coordinates without tapping`;
+        }
         // Check for LogBox overlay (uses default CDP device — native deviceId cannot be mapped to CDP device name)
         try {
             const logBoxState = await detectLogBox();
@@ -3205,7 +3210,7 @@ registerToolWithTelemetry("list_ios_simulators", {
 });
 // Tool: iOS screenshot
 registerToolWithTelemetry("ios_screenshot", {
-    description: "Take a screenshot from an iOS simulator. Returns the image data that can be displayed.",
+    description: "Take a screenshot from an iOS simulator. Returns the image and a screen layout overlay showing visible React components with names, text content, hierarchy, and tap-ready pixel coordinates. Use component names for inspect_component/find_components. Use tap(text=...) for interaction — only fall back to tap(x,y) coordinates from the layout if all tap strategies fail.",
     inputSchema: {
         outputPath: z
             .string()
@@ -3289,6 +3294,14 @@ registerToolWithTelemetry("ios_screenshot", {
             pointHeight = Math.round(pixelHeight / scaleFactor);
         }
         const safeAreaOffsetPixels = safeAreaTop * scaleFactor;
+        // Enrich with screen layout data (component names + tap coordinates)
+        let layoutText = null;
+        try {
+            layoutText = await enrichScreenshotWithLayout(scaleFactor, result.scaleFactor || 1);
+        }
+        catch {
+            // Non-fatal: screenshot works without layout enrichment
+        }
         let infoText = `Screenshot captured (${pixelWidth}x${pixelHeight} pixels)`;
         infoText += `\n📱 iOS screen: ${pointWidth}x${pointHeight} points (${scaleFactor}x scale)`;
         infoText += `\n📐 tap() handles pixel-to-point conversion automatically — pass pixel coords from this image directly`;
@@ -3296,11 +3309,22 @@ registerToolWithTelemetry("ios_screenshot", {
         if (result.scaleFactor && result.scaleFactor > 1) {
             infoText += `\n🖼️ Image was scaled down to fit API limits (scale: ${result.scaleFactor.toFixed(3)})`;
         }
-        infoText += `\n\n💡 Next steps:`;
-        infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
-        infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
-        infoText += `\n  • ios_describe_all — get full UI tree with exact tap coordinates`;
-        infoText += `\n  • ios_find_element(label="...") — find element coordinates without tapping`;
+        if (layoutText) {
+            infoText += `\n\n📋 Screen Layout (components with tap coordinates in pixels):`;
+            infoText += `\n${layoutText}`;
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text (preferred)`;
+            infoText += `\n  • tap(testID="id") or tap(component="Name") — tap by testID or component name`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — use tap coordinates from layout above ONLY if text/testID/component tap fails`;
+            infoText += `\n  • inspect_component("ComponentName") — inspect a component from the layout above`;
+        }
+        else {
+            infoText += `\n\n💡 Next steps:`;
+            infoText += `\n  • tap(text="Button Label") — tap element by visible text`;
+            infoText += `\n  • tap(x=<px>, y=<px>) — tap at coordinates from this screenshot`;
+            infoText += `\n  • ios_describe_all — get full UI tree with exact tap coordinates`;
+            infoText += `\n  • ios_find_element(label="...") — find element coordinates without tapping`;
+        }
         // Check for LogBox overlay (uses default CDP device — native UDID cannot be mapped to CDP device name)
         try {
             const logBoxState = await detectLogBox();
@@ -3359,32 +3383,39 @@ registerToolWithTelemetry("ocr_screenshot", {
             .describe("Optional device ID (Android) or UDID (iOS). Uses first available device if not specified.")
     }
 }, async ({ platform, deviceId }) => {
-    // Call the HTTP endpoint for OCR (allows hot-reload without session restart)
-    // Prefer child process port, fall back to in-process port
-    const port = getDebugServerPort();
-    if (!port) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "Debug HTTP server not running"
-                }
-            ],
-            isError: true
-        };
-    }
     try {
-        const params = new URLSearchParams({ platform, engine: "auto" });
-        if (deviceId)
-            params.set("deviceId", deviceId);
-        const response = await fetch(`http://localhost:${port}/api/ocr?${params}`);
-        const ocrResult = await response.json();
+        // Take screenshot
+        const screenshotResult = platform === "android"
+            ? await androidScreenshot(undefined, deviceId)
+            : await iosScreenshot(undefined, deviceId);
+        if (!screenshotResult.success || !screenshotResult.data) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Screenshot failed: ${screenshotResult.error || "No image data"}`
+                    }
+                ],
+                isError: true
+            };
+        }
+        // Calculate device pixel ratio for iOS
+        const devicePixelRatio = platform === "ios" && screenshotResult.originalWidth && screenshotResult.originalHeight
+            ? inferIOSDevicePixelRatio(screenshotResult.originalWidth, screenshotResult.originalHeight)
+            : 1;
+        // Run OCR on the screenshot
+        const scaleFactor = screenshotResult.scaleFactor || 1;
+        const ocrResult = await recognizeText(screenshotResult.data, {
+            scaleFactor,
+            platform,
+            devicePixelRatio
+        });
         if (!ocrResult.success) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `OCR failed: ${ocrResult.error || "Unknown error"}`
+                        text: `OCR failed: no text recognized`
                     }
                 ],
                 isError: true
@@ -3419,25 +3450,20 @@ registerToolWithTelemetry("ocr_screenshot", {
         catch {
             // Non-fatal: LogBox detection failure should not break OCR
         }
-        // Capture screenshot and store in image buffer
+        // Store screenshot in image buffer
         try {
-            const screenshotResult = platform === "android"
-                ? await androidScreenshot(undefined, deviceId)
-                : await iosScreenshot(undefined, deviceId);
-            if (screenshotResult.success && screenshotResult.data) {
-                imageBuffer.add({
-                    id: `ocr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-                    image: screenshotResult.data,
-                    timestamp: Date.now(),
-                    source: "ocr_screenshot",
-                    metadata: {
-                        width: screenshotResult.originalWidth || 0,
-                        height: screenshotResult.originalHeight || 0,
-                        scaleFactor: screenshotResult.scaleFactor || 1,
-                        platform,
-                    },
-                });
-            }
+            imageBuffer.add({
+                id: `ocr-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+                image: screenshotResult.data,
+                timestamp: Date.now(),
+                source: "ocr_screenshot",
+                metadata: {
+                    width: screenshotResult.originalWidth || 0,
+                    height: screenshotResult.originalHeight || 0,
+                    scaleFactor,
+                    platform,
+                },
+            });
         }
         catch {
             // Non-fatal: image buffer write failure should not break OCR response
@@ -3456,7 +3482,7 @@ registerToolWithTelemetry("ocr_screenshot", {
             content: [
                 {
                     type: "text",
-                    text: `OCR request failed: ${error instanceof Error ? error.message : String(error)}`
+                    text: `OCR failed: ${error instanceof Error ? error.message : String(error)}`
                 }
             ],
             isError: true
@@ -3830,57 +3856,6 @@ server.registerTool("ios_wait_for_element", {
         content: [{ type: "text", text: info }]
     };
 });
-// Tool: Get debug server info
-registerToolWithTelemetry("get_debug_server", {
-    description: "Get the debug HTTP server URL. Use this to find where you can access logs, network requests, and other debug data via HTTP.",
-    inputSchema: {}
-}, async () => {
-    const port = getDebugServerPort();
-    if (!port) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: "Debug HTTP server is not running."
-                }
-            ],
-            isError: true
-        };
-    }
-    const info = {
-        url: `http://localhost:${port}`,
-        endpoints: {
-            status: `http://localhost:${port}/api/status`,
-            logs: `http://localhost:${port}/api/logs`,
-            network: `http://localhost:${port}/api/network`,
-            bundleErrors: `http://localhost:${port}/api/bundle-errors`,
-            apps: `http://localhost:${port}/api/apps`
-        }
-    };
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Debug HTTP server running at:\n\n${JSON.stringify(info, null, 2)}`
-            }
-        ]
-    };
-});
-// Tool: Restart HTTP server (hot-reload)
-registerToolWithTelemetry("restart_http_server", {
-    description: "Note: HTTP server now runs in-process to share state. To apply code changes, restart the MCP session.",
-    inputSchema: {}
-}, async () => {
-    const port = getDebugServerPort();
-    return {
-        content: [
-            {
-                type: "text",
-                text: `HTTP server is running in-process on port ${port}. To apply code changes, rebuild with 'npm run build' and restart the MCP session. The in-process mode is required for the dashboard to show logs, network requests, and connected apps.`
-            }
-        ]
-    };
-});
 // Tool: Activate Pro license
 registerToolWithTelemetry("activate_license", getActivateLicenseConfig(), handleActivateLicense);
 // Tool: Delete account
@@ -3908,10 +3883,6 @@ async function main() {
     // License validation is lazy — runs on first tool use via ensureLicense()
     initTelemetry();
     identifyIfDevMode(getInstallationId());
-    // Start debug HTTP server in-process (shares state with MCP server)
-    // Note: Child process mode doesn't work because state (logs, network, apps) isn't shared
-    await startDebugHttpServer();
-    console.error("[rn-ai-debugger] HTTP server started in-process");
     // --- Eager usage check (pre-loads usage cache for tool-level gate) ---
     const { ensureLicense } = await import("./core/license.js");
     await ensureLicense();