feat: element refs in dump ui, tap by @ref

[gmegidish]

Summary

• dump ui now assigns each element a ref (e1..eN, depth-first pre-order — the element's position in the printed tree).
• io tap accepts either x,y coordinates or an element ref (@e5). A ref is resolved against a fresh dump at tap time and taps the element's rect center. JSON-RPC device.io.tap accepts the new ref field as well.
• Raw dumps (--format raw) are unchanged.

Refs are positional against the latest dump, so they are only valid until the screen changes; no staleness tracking yet.

Test plan

• go test ./types ./commands (new tests for ref numbering and nested ref lookup)
• Manual: mobilecli dump ui then mobilecli io tap @e3
• Error message check: io tap e15 suggests both formats

Summary by CodeRabbit

• New Features

  • io tap now supports tapping UI elements by reference, such as @e5, in addition to screen coordinates.
  • Screen element references are included in structured UI information, including nested elements.
  • Reference-based taps automatically target the matched element’s center.

• Bug Fixes

  • Improved validation and error reporting for invalid tap targets.

• Tests

  • Added coverage for nested element references and reference-based tapping.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Essentials

Run ID: 58d1164d-3887-49bc-a7ca-4fab043e598f

📥 Commits

Reviewing files that changed from the base of the PR and between 4ebb1a9 and 988258c.

📒 Files selected for processing (1)

• commands/input.go

Included review availability: 0 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

---

📝 Walkthrough

Walkthrough

The io tap command accepts coordinates or element references. Structured UI dumps assign depth-first references to elements. Reference-based taps resolve the current element and tap its center.

Changes

Element-reference tapping

Layer / File(s)	Summary
Reference contracts and numbering types/screen.go, types/screen_test.go	ScreenElement stores an optional reference. AttachRefs assigns e1-style references in depth-first pre-order. Tests cover nested and sibling elements.
Reference attachment in UI dumps commands/dump.go	Structured UI dumps attach references before returning elements.
Reference-aware tap execution commands/input.go, commands/input_test.go, cli/io.go	TapCommand resolves references from a fresh dump, taps the matched element center, and retains coordinate validation when no reference is supplied. io tap accepts coordinate pairs and @-prefixed references.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 98825

The PR adds element references for UI dumps and allows tapping by reference or coordinates; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as io tap
  participant TapCommand
  participant UIDump as structured UI dump
  participant Device
  CLI->>TapCommand: pass Ref or coordinates
  TapCommand->>UIDump: fetch current elements
  UIDump-->>TapCommand: return referenced elements
  TapCommand->>TapCommand: resolve Ref and calculate center
  TapCommand->>Device: tap coordinates

Loading

Suggested reviewers: hakanor

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.56% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 6 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: adding element references to UI dumps and supporting taps by reference.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/element-refs

---

_{Comment @coderabbitai help to get the list of available commands.}