execbro 2.1.2 → 2.3.0

package/build/core/textEntry.js

@@ -0,0 +1,252 @@
+import { resolveWrittenField } from "./nativeInputValue.js";
+/**
+ * Names the likely cause of a mismatch. The field's own keyboard settings
+ * transform text on the way in, and "landed differently" alone sends the
+ * reader hunting for a bug in the write when the write was fine.
+ */
+export function diagnoseMismatch(sent, landed) {
+    if (landed === null)
+        return "";
+    if (landed !== sent && landed.toLowerCase() === sent.toLowerCase()) {
+        return " — only the capitalisation differs, which is the field's keyboard transforming input" +
+            " (RN TextInput defaults autoCapitalize to 'sentences'); set autoCapitalize=\"none\" to type verbatim";
+    }
+    if (landed.replace(/\s+/g, "") === sent.replace(/\s+/g, "")) {
+        return " — only whitespace differs, which is usually iOS smart punctuation or autocorrect spacing";
+    }
+    if (landed.length === sent.length && [...landed].sort().join("") === [...sent].sort().join("")) {
+        return " — the same characters arrived in a different order, which is the HID keystroke race;" +
+            " the retry already ran, so this one did not settle";
+    }
+    return "";
+}
+/**
+ * Whether the HID driver can express this text at all.
+ *
+ * AXe types US-keyboard HID keycodes: A-Z, a-z, 0-9, space and the ASCII
+ * symbols. Nothing outside that map has a keycode to send — which rules out
+ * Cyrillic and CJK, and equally Spanish accents (á, ñ, ü), a case that is easy
+ * to miss because the text otherwise looks Latin. `adb shell input text` is no
+ * better: non-ASCII throws a NullPointerException inside InputShellCommand.
+ */
+export function isHidTypeable(text) {
+    // Printable ASCII plus tab/newline. Deliberately excludes the C1 range and
+    // anything above 0x7E.
+    return /^[\x20-\x7E\t\n]*$/.test(text);
+}
+function queryOf(a) {
+    const q = {};
+    if (a.testID != null)
+        q.testID = a.testID;
+    if (a.component != null)
+        q.component = a.component;
+    if (a.textMatch != null)
+        q.textMatch = a.textMatch;
+    if (a.index != null)
+        q.index = a.index;
+    return Object.keys(q).length > 0 ? q : undefined;
+}
+/**
+ * Resolve -> focus -> write -> read back -> retry once -> raise keyboard.
+ *
+ * The read-back comparison is EXACT. The corruption reproduced on device is a
+ * reorder (CASEB -> CSEBA), which every loose check — length, non-empty,
+ * prefix — passes. A success from this function means the field holds the
+ * requested string, or it says it could not confirm that.
+ */
+export async function enterText(args, deps) {
+    const q = queryOf(args);
+    // 1. Resolve. A miss is a hard failure — this is precisely where the old
+    //    tools typed into the void and reported success.
+    const target = await deps.runOp({ kind: "find" }, q, args.device);
+    if (!target.found) {
+        return {
+            success: false,
+            error: target.reason,
+            ...(target.ambiguous && { ambiguous: true }),
+            ...(target.candidates && { candidates: target.candidates }),
+            ...(target.totalInputs !== undefined && { totalInputs: target.totalInputs })
+        };
+    }
+    // 2. Focus it ourselves if needed. A tap reporting success does not
+    //    guarantee React focus — reproduced on device.
+    if (!target.focused) {
+        const focused = await deps.runOp({ kind: "focus" }, q, args.device);
+        if (!focused.found)
+            return { success: false, error: focused.reason };
+        if (!focused.ok)
+            return { success: false, error: focused.via ?? "could not focus the input" };
+    }
+    // An uncontrolled field's current text is not in props, so `target.value` is
+    // always null for one. Taking that as "" made append silently behave as
+    // replace, and the retry then CLEARED the field to make the wrong answer
+    // verify clean. The accessibility tree is the only place the real previous
+    // text exists, so it has to be read before `desired` is computed.
+    let nativeBefore = [];
+    const usesNativeReadBack = !target.controlled && deps.readNativeFields !== undefined;
+    let previous = target.value ?? "";
+    let previousKnown = target.controlled;
+    if (usesNativeReadBack) {
+        nativeBefore = (await deps.readNativeFields()).fields;
+        const current = resolveWrittenField(nativeBefore, nativeBefore, target.testID);
+        if (current && current.text !== null) {
+            previous = current.text;
+            previousKnown = true;
+        }
+    }
+    const desired = args.replace ? args.text : previous + args.text;
+    // Three paths, chosen by what the field can actually honour:
+    //
+    //   controlled            -> onChangeText. The value prop mirrors the text,
+    //                            so this both writes and stays verifiable.
+    //   uncontrolled + handler, ASCII -> real keystrokes. The most faithful
+    //                            simulation, and the retry now catches its
+    //                            keystroke race, so the racy path is only taken
+    //                            where it can actually succeed.
+    //   uncontrolled + handler, non-ASCII -> setNativeProps AND a direct
+    //                            onChangeText call. HID cannot express these
+    //                            characters at all, so faithfulness is not on
+    //                            offer; firing the handler is what keeps the
+    //                            app from missing text the field displays.
+    //   uncontrolled, no handler -> setNativeProps. Nothing to fire.
+    // `fromEmpty` says whether the field was just cleared. It matters only for
+    // HID, which appends at the caret rather than setting a value: typing the
+    // delta into a populated field is right, but typing it into a cleared one
+    // would lose whatever came before.
+    const write = async (fromEmpty) => {
+        if (target.controlled) {
+            const r = await deps.runOp({ kind: "setValue", value: desired }, q, args.device);
+            return { path: "react", ok: r.found && r.ok, error: r.found ? r.via : r.reason };
+        }
+        if (target.hasOnChangeText && isHidTypeable(args.text)) {
+            const r = await deps.typeHid(fromEmpty ? desired : args.text);
+            return { path: "hid", ok: r.success, error: r.error };
+        }
+        const r = await deps.runOp({ kind: "setNative", value: desired }, q, args.device);
+        return { path: "native", ok: r.found && r.ok, error: r.found ? r.via : r.reason };
+    };
+    // `undefined` from readBack means "could not determine" and must surface as
+    // unverified — never as a mismatch, which is what comparing against an
+    // always-null read produced before.
+    const readBack = async () => {
+        if (target.controlled) {
+            const r = await deps.runOp({ kind: "read" }, q, args.device);
+            return r.found ? r.value : null;
+        }
+        if (!usesNativeReadBack)
+            return undefined;
+        // A native write updates the view asynchronously, and the accessibility
+        // dump is a separate process — reading immediately captures the state
+        // from before the write. Poll until the text appears, then stop. Going
+        // through MCP hid this because the call latency happened to cover it.
+        const wait = deps.delay ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        let last;
+        for (const ms of [0, 250, 500]) {
+            if (ms > 0)
+                await wait(ms);
+            const after = await deps.readNativeFields();
+            if (after.error) {
+                last = undefined;
+                continue;
+            }
+            const hit = resolveWrittenField(nativeBefore, after.fields, target.testID);
+            last = hit ? hit.text : undefined;
+            if (last === desired)
+                return last;
+        }
+        return last;
+    };
+    // HID appends at the caret, so a replace must clear first or it concatenates.
+    const needsClearFirst = args.replace === true && !target.controlled && target.hasOnChangeText &&
+        isHidTypeable(args.text) && previous.length > 0;
+    if (needsClearFirst)
+        await deps.runOp({ kind: "clear" }, q, args.device);
+    const first = await write(needsClearFirst);
+    if (!first.ok) {
+        // A failed replace already cleared the field. Put it back rather than
+        // leaving the user's data destroyed with no mention of it.
+        if (args.replace && target.hasOnChangeText && previous.length > 0) {
+            const restored = await deps.runOp({ kind: "setValue", value: previous }, q, args.device);
+            return {
+                success: false,
+                path: first.path,
+                error: `${first.error ?? "write failed"} (previous value ${restored.found && restored.ok ? "restored" : "COULD NOT be restored"})`
+            };
+        }
+        return { success: false, path: first.path, error: first.error ?? "write failed" };
+    }
+    let landed = await readBack();
+    // Could not read the field at all — say so instead of guessing either way.
+    if (landed === undefined) {
+        const keyboard = await deps.raise();
+        return {
+            success: true,
+            path: first.path,
+            verified: false,
+            keyboard,
+            error: target.controlled
+                ? "the value could not be read back"
+                : "this field is uncontrolled and could not be located in the accessibility tree" +
+                    (target.testID ? "" : " (it has no testID, and no single field's text changed)")
+        };
+    }
+    let retried = false;
+    if (landed !== desired) {
+        retried = true;
+        // Clear only for HID, which appends at the caret. The other paths set
+        // the whole value, so a clear is redundant — and actively harmful:
+        // publicInstance.clear() after HID typing races the setNativeProps that
+        // follows and wipes it, which made every non-ASCII retry land empty.
+        const clearedForRetry = first.path === "hid";
+        if (clearedForRetry) {
+            await deps.runOp({ kind: "clear" }, q, args.device);
+        }
+        else {
+            // A native write immediately after another input operation is
+            // sometimes swallowed — the value simply does not change. Give the
+            // previous operation a beat to settle before rewriting, rather than
+            // repeating the same call into the same contention.
+            const wait = deps.delay ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+            await wait(300);
+        }
+        const second = await write(clearedForRetry);
+        if (!second.ok) {
+            return { success: false, path: second.path, retried, error: second.error ?? "rewrite failed" };
+        }
+        landed = await readBack();
+    }
+    if (landed !== desired) {
+        // A read that failed only on the retry is still "unconfirmed", not a
+        // mismatch — we have no evidence about what the field holds.
+        if (landed === undefined) {
+            const keyboard = await deps.raise();
+            return {
+                success: true, path: first.path, verified: false, retried, keyboard,
+                error: "the rewrite could not be read back, so the result is unconfirmed"
+            };
+        }
+        return {
+            success: false,
+            path: first.path,
+            verified: false,
+            retried,
+            sent: desired,
+            landed,
+            error: `text landed differently than it was sent${diagnoseMismatch(desired, landed)}` +
+                (!previousKnown && !args.replace
+                    ? " — note the field's prior text could not be read, so the appended result was predicted from an empty starting point; pass replace:true to write an exact value"
+                    : "")
+        };
+    }
+    // Last, and never fatal.
+    const keyboard = await deps.raise();
+    return {
+        success: true,
+        value: landed,
+        path: first.path,
+        verified: true,
+        ...(retried && { retried }),
+        keyboard
+    };
+}
+//# sourceMappingURL=textEntry.js.map

package/build/core/textEntry.js.map

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

package/build/tools/componentTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"componentTools.d.ts","sourceRoot":"","sources":["../../src/tools/componentTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA0CzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0uB9D"}
+{"version":3,"file":"componentTools.d.ts","sourceRoot":"","sources":["../../src/tools/componentTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsDzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAqkB9D"}

package/build/tools/componentTools.js

@@ -1,9 +1,28 @@
 import { z } from "zod";
 import { registerToolWithTelemetry } from "../core/register.js";
-import { iconLabel } from "../core/iconSemantics.js";
-import { getComponentTree, getScreenLayout, getPressableElements, getScreenState, formatScreenStateSummary, inspectComponent, findComponents, harvestStacksAtPoint, enrichWithSource, inspectAtPoint, measureComponent, iosScreenshot, androidScreenshot, androidGetDensity, getDevicePixelRatio, getIOSSafeAreaTop, inferIOSDevicePixelRatio, metroMissingHintIfAbsent, hasMetro, getConnectedAppByDevice, getFirstConnectedApp, } from "../core/index.js";
+import { getComponentTree, getScreenLayout, getScreenState, formatScreenStateSummary, inspectComponent, findComponents, harvestStacksAtPoint, enrichWithSource, inspectAtPoint, measureComponent, metroMissingHintIfAbsent, hasMetro, getConnectedAppByDevice, getFirstConnectedApp, } from "../core/index.js";
+import { screenStateToScreenSpace, toScreenSpaceY } from "../core/screenSpace.js";
+import { resolveScreenSpaceMetrics } from "../core/screenSpaceDevice.js";
+import { readKeyboardState } from "../core/keyboardMetrics.js";
 import { primaryInteractionBanner } from "../core/toolHelpers.js";
 import { DEVICE_ARG_DESC } from "./_deviceArg.js";
+/**
+ * Top inset for whichever device a layout tool is about to answer for.
+ *
+ * A zero inset is the safe default: {@link toScreenSpaceY} treats it as "leave coordinates
+ * alone", so an unresolvable device degrades to the previous raw-fiber behaviour rather
+ * than to a wrongly shifted one.
+ */
+async function resolveScreenSpaceMetricsFor(device) {
+    const app = (device ? getConnectedAppByDevice(device) : getFirstConnectedApp()) ?? getFirstConnectedApp();
+    if (!app)
+        return { platform: "ios", topInset: 0 };
+    return resolveScreenSpaceMetrics({
+        platform: app.platform,
+        udid: app.simulatorUdid,
+        deviceId: app.adbSerial
+    });
+}
 function collectMetaNotes(r) {
     const out = [];
     if (r._meta?.reconnected) {
@@ -17,7 +36,7 @@ function collectMetaNotes(r) {
 export function registerComponentTools(server) {
     // Tool: Get full screen layout (all components with layout styles)
     registerToolWithTelemetry(server, "get_screen_layout", {
-        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 extended=true to include layout styles (padding, margin, flex, backgroundColor, etc.)." +
+        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 screen space — the same space screenshots, get_screen_state and tap() use, so pass them through unchanged. Use extended=true to include layout styles (padding, margin, flex, backgroundColor, etc.)." +
             primaryInteractionBanner() + "\n" +
             "PURPOSE: Quickest textual map of what is actually on screen right now — component names, positions, and text — so you can plan taps and inspections without guessing.\n" +
             "WHEN TO USE: First step whenever the user asks \"what's on screen\", \"why is X covering Y\", or before tapping a visually ambiguous element.\n" +
@@ -52,7 +71,13 @@ export function registerComponentTools(server) {
             };
         }
         const effectiveTimeoutMs = timeoutMs ?? (extended ? 15000 : 5000);
-        const result = await getScreenLayout({ extended, summary, device, timeoutMs: effectiveTimeoutMs });
+        const result = await getScreenLayout({
+            extended,
+            summary,
+            device,
+            timeoutMs: effectiveTimeoutMs,
+            screenSpace: await resolveScreenSpaceMetricsFor(device)
+        });
         const metaNotes = collectMetaNotes(result);
         if (!result.success) {
             const errText = metaNotes.length > 0 ? `Error: ${result.error}\n\n${metaNotes.join("\n")}` : `Error: ${result.error}`;
@@ -139,129 +164,13 @@ export function registerComponentTools(server) {
             : `React Component Tree:\n\n${result.result}`;
         return { content: [{ type: "text", text: body }] };
     });
-    // Tool: Get all pressable elements on screen
-    registerToolWithTelemetry(server, "get_pressable_elements", {
-        description: "Prefer get_screen_state after navigation (route + overlays + pressables in one call).\n\n" +
-            "Find all pressable (onPress) and input (TextInput) elements currently visible on screen. Returns component names, ready-to-tap center coordinates in SCREENSHOT PIXELS (same space as ios_screenshot/android_screenshot — pass directly to tap(x, y)), text labels, testID, accessibilityLabel, and a spatial nearbyText hint for icon-only buttons. Each element includes hasLabel (true if it contains text) and isInput (true for TextInput fields).\n" +
-            "HELPER — call before `tap` when you need to enumerate candidate elements before committing to a target; not a replacement for tap itself.\n" +
-            "PURPOSE: Produce a ready-to-tap inventory of every interactive element on screen with screenshot-pixel coordinates that tap(x, y) accepts directly.\n" +
-            "WHEN TO USE: Before tapping icon-only buttons, when text-based tap keeps failing, or to enumerate what the user can actually interact with.\n" +
-            "WORKFLOW: ios_screenshot / android_screenshot -> get_pressable_elements -> tap(testID=\"...\") or tap(x, y) using the center coordinates.\n" +
-            "LIMITATIONS: Visible-only (off-screen pressables are excluded). Requires a live React connection. Coordinates are in screenshot pixels — the tap tool converts to points internally.\n" +
-            "GOOD: get_pressable_elements()\n" +
-            "BAD: Calling when tap(testID=\"...\") already works — testID matching is faster and more stable.\n",
-        inputSchema: {
-            device: z.string().optional().describe(DEVICE_ARG_DESC)
-        }
-    }, async ({ device }) => {
-        const result = await getPressableElements({ device });
-        if (!result.success) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Error: ${result.error}`
-                    }
-                ],
-                isError: true
-            };
-        }
-        const elements = result.parsedElements;
-        if (!elements || elements.length === 0) {
-            return {
-                content: [{ type: "text", text: result.result || "No pressable elements found." }]
-            };
-        }
-        // Resolve target app so we can pick the right simulator / android device
-        const targetApp = device ? getConnectedAppByDevice(device) : getFirstConnectedApp();
-        if (!targetApp) {
-            // No connected app — return raw (points) output; better than nothing
-            return {
-                content: [{ type: "text", text: result.result || "No pressable elements found." }]
-            };
-        }
-        // Capture a lightweight screenshot to learn scaleFactor (downscale) and dimensions.
-        // Conversion: screenshot_px = native_coord * devicePixelRatio / screenshotScale
-        let lines = [];
-        try {
-            if (targetApp.platform === "ios") {
-                const udid = targetApp.simulatorUdid;
-                const shot = await iosScreenshot(undefined, udid);
-                const screenshotScale = shot.scaleFactor || 1;
-                const devicePixelRatio = (shot.originalWidth && shot.originalHeight
-                    ? inferIOSDevicePixelRatio(shot.originalWidth, shot.originalHeight)
-                    : null) ?? (await getDevicePixelRatio(udid)) ?? 3;
-                // Fallback to 59pt (iPhone typical) when the UI driver preflight can't
-                // resolve the true inset — matches ios_screenshot's default. Without this
-                // shift, react-native-screens modal-presented screens report y relative
-                // to content origin and taps land in the status bar instead of the button.
-                const safeAreaTop = (await getIOSSafeAreaTop(udid).catch(() => 0)) || 59;
-                // Keep the app's lastScreenshot metadata in sync so tap(x, y) uses the
-                // same scaleFactor when converting our pixel coords back to points.
-                if (shot.originalWidth && shot.originalHeight) {
-                    targetApp.lastScreenshot = {
-                        originalWidth: shot.originalWidth,
-                        originalHeight: shot.originalHeight,
-                        scaleFactor: screenshotScale
-                    };
-                }
-                lines = formatPressablesInPixels(elements, {
-                    platform: "ios",
-                    devicePixelRatio,
-                    screenshotScale,
-                    safeAreaTop
-                });
-            }
-            else {
-                // Metro's `deviceName` is the device model (e.g. "sdk_gphone16k_arm64"),
-                // not the adb serial (e.g. "emulator-5554"), so passing it as -s makes
-                // adb miss the device and androidScreenshot/androidGetDensity silently
-                // return defaults (scale=1, density=160). That leaves coords in raw
-                // device pixels — off by ~1.2× from the screenshot/JPEG space the tool
-                // description promises. Pass undefined to let adb auto-pick (matches
-                // how android_screenshot works when called without deviceId). Multi-
-                // Android-device support tracks separately under the multi-device
-                // refactor; this path is a single-Android-device fix.
-                const shot = await androidScreenshot(undefined, undefined);
-                const screenshotScale = shot.scaleFactor || 1;
-                const density = await androidGetDensity(undefined).catch(() => ({ density: 160 }));
-                const devicePixelRatio = (density.density || 160) / 160;
-                if (shot.originalWidth && shot.originalHeight) {
-                    targetApp.lastScreenshot = {
-                        originalWidth: shot.originalWidth,
-                        originalHeight: shot.originalHeight,
-                        scaleFactor: screenshotScale
-                    };
-                }
-                lines = formatPressablesInPixels(elements, {
-                    platform: "android",
-                    devicePixelRatio,
-                    screenshotScale,
-                    safeAreaTop: 0
-                });
-            }
-        }
-        catch {
-            // Fallback to points if screenshot/metadata unavailable
-            return {
-                content: [{ type: "text", text: result.result || "No pressable elements found." }]
-            };
-        }
-        const iconCount = elements.filter((e) => !e.hasLabel).length;
-        const labeledCount = elements.length - iconCount;
-        const summary = `Found ${elements.length} pressable elements (${iconCount} icon-only, ${labeledCount} with text labels)`;
-        const text = [summary, "", ...lines].join("\n");
-        return {
-            content: [{ type: "text", text }]
-        };
-    });
     // Tool: Get current screen state — route, overlays, pressables (post-navigation checkpoint)
     registerToolWithTelemetry(server, "get_screen_state", {
         description: "Screenshot-free snapshot of the current screen: active route + params, blocking overlays (sheets, modals, alerts), and every on-screen element merged top-to-bottom within reachability groups. Call after any tap or navigation to orient before the next action. " +
             "Each line carries an (x, y) center + frame bounds (so anything is a tap(x, y) target), typed by a leading marker: 🔘 pressable (with component JSX tag, label, testID, onPress hint), 📝 text, 🖼 image (with src/alt). " +
             "Elements covered by an open overlay are grouped under 🚫 Blocked — visible for context, but taps will NOT reach them until the overlay closes. Long text truncates to 80 chars (fullText=true for full strings); pressablesOnly=true returns just the lean tappable list.\n\n" +
             "WHEN TO USE: After every tap/swipe that may navigate, and to read screen content (prices, labels, which image loaded) without a screenshot+OCR round-trip.\n" +
-            "LIMITATIONS: route is null without React Navigation / Expo Router. Requires a live Metro connection. Coordinates in points (iOS) / dp (Android); text frames are container-level (climb to nearest measurable host).\n" +
+            "LIMITATIONS: route is null without React Navigation / Expo Router. Requires a live Metro connection.\n" +
             "SOURCE: this lists what is on screen, not where it lives in code — for the file:line that renders an element, call inspect_at_point(x, y).\n" +
             "SEE ALSO: get_screen_layout for the full hierarchical component tree (deep inspection) — this gives a flat, tap-ready content list instead.",
         inputSchema: {
@@ -277,7 +186,13 @@ export function registerComponentTools(server) {
                 isError: true
             };
         }
-        const result = await getScreenState({ device });
+        // In parallel: the keyboard read is a second CDP round trip and has
+        // no reason to queue behind the fiber walk. It degrades to
+        // { visible: false, error } on failure, so it cannot fail this call.
+        const [result, keyboard] = await Promise.all([
+            getScreenState({ device }),
+            readKeyboardState(device)
+        ]);
         const metaNotes = collectMetaNotes(result);
         if (!result.success) {
             const errText = metaNotes.length > 0
@@ -288,69 +203,18 @@ export function registerComponentTools(server) {
                 isError: true
             };
         }
-        const ss = result.screenState;
-        const summary = ss ? formatScreenStateSummary(ss, undefined, { pressablesOnly, fullText }) : (result.result ?? "{}");
+        // Normalise to screen space so a coordinate read here can be handed straight to
+        // tap()/inspect_at_point/a screenshot. Raw measureInWindow is not screen-relative
+        // (Android excludes the status bar; iOS modals measure from their own container),
+        // which is why point-space output used to disagree with screenshot pixels.
+        const rawSs = result.screenState;
+        const ss = rawSs ? screenStateToScreenSpace(rawSs, await resolveScreenSpaceMetricsFor(device)) : rawSs;
+        const summary = ss ? formatScreenStateSummary(ss, undefined, { pressablesOnly, fullText, keyboard }) : (result.result ?? "{}");
         const body = metaNotes.length > 0
             ? `${summary}\n\n${metaNotes.join("\n")}`
             : summary;
         return { content: [{ type: "text", text: body }] };
     });
-    function formatPressablesInPixels(elements, opts) {
-        const { platform, devicePixelRatio, screenshotScale, safeAreaTop } = opts;
-        const out = [];
-        for (let i = 0; i < elements.length; i++) {
-            const el = elements[i];
-            // react-native-screens modal presentations report y relative to content origin;
-            // shift into the window frame when the element's center sits inside the safe-area
-            // band. The shift MUST be applied to center and frame atomically — independent
-            // checks (cy<inset, fy<inset) drift apart on iPad-style insets where a header's
-            // center is just below the inset but its frame top is just above, producing
-            // center/frame.y values that don't satisfy center = frame.y + frame.h/2.
-            let cy = el.center.y;
-            let fy = el.frame.y;
-            if (platform === "ios" && safeAreaTop > 0 && cy < safeAreaTop) {
-                cy += safeAreaTop;
-                fy += safeAreaTop;
-            }
-            // iOS: fiber returns points → convert points × DPR / screenshotScale = JPEG px.
-            // Android: getPressableElements reconciles fiber DP against uiautomator device-pixel
-            // bounds (executor.ts, 2026-05-17). After reconciliation, coords are already in
-            // device pixels — only the JPEG downscale needs to be applied. Multiplying by DPR
-            // here would re-inflate them by ~density/160 (~2.6× on a 420dpi device), reproducing
-            // the original out-of-bounds bug.
-            const toPx = (v) => platform === "android"
-                ? Math.round(v / screenshotScale)
-                : Math.round((v * devicePixelRatio) / screenshotScale);
-            const cx = toPx(el.center.x);
-            const cyPx = toPx(cy);
-            const fx = toPx(el.frame.x);
-            const fyPx = toPx(fy);
-            const fw = toPx(el.frame.width);
-            const fh = toPx(el.frame.height);
-            const num = i + 1;
-            const iconHint = !el.hasLabel ? iconLabel(el.component, el.icon) : null;
-            const label = el.hasLabel
-                ? `"${el.text}"`
-                : iconHint
-                    ? `(${iconHint})`
-                    : el.intent
-                        ? `(${el.intent} icon)`
-                        : "(icon/image)";
-            const ids = [];
-            if (el.testID)
-                ids.push(`testID="${el.testID}"`);
-            if (el.accessibilityLabel)
-                ids.push(`a11y="${el.accessibilityLabel}"`);
-            const idStr = ids.length > 0 ? ` [${ids.join(", ")}]` : "";
-            const inputStr = el.isInput ? " (input)" : "";
-            const wrapperStr = el.isWrapper ? " [wrapper — skip unless dismissing keyboard]" : "";
-            const nearPart = el.nearbyText ? ` near "${el.nearbyText}"` : "";
-            out.push(`${num}. ${el.component} ${label}${nearPart} — center:(${cx},${cyPx}) frame:(${fx},${fyPx} ${fw}x${fh})${idStr}${inputStr}${wrapperStr}`);
-            if (el.path)
-                out.push(`   path: ${el.path}`);
-        }
-        return out;
-    }
     // Tool: Inspect a specific component by name
     registerToolWithTelemetry(server, "inspect_component", {
         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." +
@@ -492,16 +356,16 @@ export function registerComponentTools(server) {
         description: "Inspect layout AND props at (x, y). Returns FRAME PER ANCESTOR (position/size in dp for every ancestor that hit-tested the point) + the innermost component's PROPS (handlers as [Function], refs, custom props like onPress/data/testID). Pure JS hit-test via fiber + measureInWindow — no overlay toggled, zero visual side effect. Works on Paper and Fabric.\n" +
             "PURPOSE: Layout/props diagnosis — \"where is each ancestor positioned, and what props does the touched component expose?\"\n" +
             "WHEN TO USE: A button is clipped, hit area is wrong, animated frame is unexpected — or you need handler/ref/non-style props. Also preferred for tight loops (no overlay flicker).\n" +
-            "WORKFLOW: screenshot → suspect pixel → divide by pixel ratio → inspect_at_point(x, y).\n" +
-            "LIMITATIONS: Coordinates MUST be in dp, not screenshot pixels — wrong unit = wrong node. Style is the node's own style object, not the merged cascade.\n" +
+            "WORKFLOW: screenshot or get_screen_state → take the coordinate as-is → inspect_at_point(x, y).\n" +
+            "LIMITATIONS: Style is the node's own style object, not the merged cascade. `frame` is the element's own box; `hitFrame` (when present) is the innermost node actually under the point.\n" +
             "SOURCE: also returns `source: {file, line, column}` for the component at the point, plus the owner chain as `Source ancestors` (set source=false to skip in tight loops).\n",
         inputSchema: {
             x: z
                 .number()
-                .describe("X coordinate in dp (logical pixels). Convert from screenshot pixels by dividing by the device pixel ratio."),
+                .describe("X coordinate in screen space — take it straight from a screenshot, get_screen_state or get_screen_layout. No conversion."),
             y: z
                 .number()
-                .describe("Y coordinate in dp (logical pixels). Convert from screenshot pixels by dividing by the device pixel ratio."),
+                .describe("Y coordinate in screen space — take it straight from a screenshot, get_screen_state or get_screen_layout. No conversion."),
             includeProps: z
                 .boolean()
                 .optional()
@@ -520,7 +384,12 @@ export function registerComponentTools(server) {
                 .describe("Resolve the component's source file and line via Metro symbolication. Default true. Set false to skip in tight loops.")
         }
     }, async ({ x, y, includeProps, includeFrame, device, source = true }) => {
-        const result = await inspectAtPoint(x, y, { includeProps, includeFrame, device });
+        const result = await inspectAtPoint(x, y, {
+            includeProps,
+            includeFrame,
+            device,
+            screenSpace: await resolveScreenSpaceMetricsFor(device)
+        });
         if (!result.success) {
             return {
                 content: [
@@ -588,7 +457,7 @@ export function registerComponentTools(server) {
     });
     // Tool: Measure on-screen geometry of a named component
     registerToolWithTelemetry(server, "measure", {
-        description: "Get on-screen geometry {x, y, width, height} for a named React component instance. Calls measureInWindow on the matched fiber (or its nearest host descendant for composite components). Coordinates are in points (iOS) / dp (Android), same space as get_screen_layout and inspect_at_point.\n" +
+        description: "Get on-screen geometry {x, y, width, height} for a named React component instance. Calls measureInWindow on the matched fiber (or its nearest host descendant for composite components). Coordinates are screen space, the same space as get_screen_layout, get_screen_state, inspect_at_point and tap().\n" +
             "PURPOSE: One-shot, name-based component measurement — avoids hand-rolling fiber walks and Promise-wrapping measureInWindow callbacks in execute_in_app.\n" +
             "WHEN TO USE: You already know the component's display name (from get_screen_layout or find_components) and just need its current bounds — e.g. to verify a layout change, compute a tap target, or compare against design specs.\n" +
             "WORKFLOW: find_components(pattern=\"...\") -> measure(componentName=\"...\", index=N) -> tap(x, y) at the center, or inspect_at_point at the center to verify identity.\n" +
@@ -626,10 +495,16 @@ export function registerComponentTools(server) {
                 _errorContext: result.outcome
             };
         }
+        // measure returns a single leaf box, so the band rule applies directly — there is
+        // no root container here to exempt. Without this the tool's own promise of "the
+        // same space as get_screen_layout and inspect_at_point" would be false: off by the
+        // status bar on every Android screen, and by the safe area inside an iOS modal.
+        const measureMetrics = await resolveScreenSpaceMetricsFor(device);
+        const measuredY = toScreenSpaceY(result.y, measureMetrics);
         const lines = [
             `Component: ${result.name}`,
-            `Frame: (${result.x.toFixed(1)}, ${result.y.toFixed(1)}) ${result.width.toFixed(1)}x${result.height.toFixed(1)}`,
-            `Center: (${(result.x + result.width / 2).toFixed(1)}, ${(result.y + result.height / 2).toFixed(1)})`,
+            `Frame: (${result.x.toFixed(1)}, ${measuredY.toFixed(1)}) ${result.width.toFixed(1)}x${result.height.toFixed(1)}`,
+            `Center: (${(result.x + result.width / 2).toFixed(1)}, ${(measuredY + result.height / 2).toFixed(1)})`,
         ];
         if (typeof result.nativeTag === "number") {
             lines.push(`nativeTag: ${result.nativeTag}`);