• aryapangestu's avatar
    docs: clarify coordinate space for input_tap/double_tap/long_press/swipe
    · a2890436
    aryapangestu создал
    Raw x/y arguments are interpreted in the most recent screenshot's pixel
    space and auto-scaled to device coordinates via screenshotScaleMap (set
    when screen_capture is called with maxWidth/maxHeight smaller than the
    device resolution). This is documented in code (`applyScale` helper) but
    NOT in tool descriptions or README, leading to surprises:
    
      - "tap(415, 820)" producing "tap(2075, 4220)" because the last
        screenshot was at preset='low' on a 1080-wide device (5× scale).
      - Confusion between coords reported by ui_find / ui_tree (which are
        device coords from uiautomator) vs raw x/y (screenshot coords) —
        passing the former as the latter when a low-res screenshot is the
        most recent capture causes silent over-scaling.
    
    Updates:
    - input_tap top-level description now spells out the coord-space rule,
      the "no screenshot taken yet" fallback (1× scale), and the ui_*-vs-raw
      pitfall. Recommends using index/text/resourceId for ui-sourced taps.
    - input_double_tap, input_long_press, input_swipe descriptions add a
      one-line cross-reference to input_tap for full rules.
    - Per-property descriptions for x/y (and x1/y1/x2/y2 in swipe) now read
      "(screenshot pixel space)" instead of generic "X coordinate".
    - README Android section gets a "Coordinate space" subsection
      explaining the model + gotchas, anchored under the Android usage
      example so users see it before they hit the surprise.
    
    No behavior change. Pure documentation. Existing 739 tests pass with
    no regressions.
    a2890436