mobile-debug-mcp 0.26.0 → 0.26.2

package/docs/ROADMAP.md

@@ -1,14 +1,26 @@
-# Mobile Debug MCP Prioritized Roadmap
+# Mobile Debug MCP Roadmap
 
-## Prioritization Criteria
+## Planning Principles
 
 Ordered by:
 
+
 1. Impact on agent reliability  
 2. Reduction in retries / brittleness  
 3. Breadth of app coverage improved  
 4. Implementation complexity vs payoff
 
+## Capability Status Definitions
+
+- **Completed**  
+  Capability implemented and considered part of the baseline platform.
+
+- **Spec Ready**  
+  Capability design or RFC is mature and implementation-ready, but not yet delivered.
+
+- **Planned**  
+  Capability is prioritized on the roadmap, but detailed specification and/or implementation work remains ahead.
+
 ## Program-Level Success Metrics
 Track roadmap impact across releases using:
 
@@ -26,23 +38,35 @@ Higher task success with fewer retries.
 
 ---
 
-# Completed
+# Roadmap Status Overview
+
+## Completed Capabilities
+
+- Stronger State Verification — Complete (Foundational verification layer shipped)
+- Richer Element Identity — Complete (Identity and selector confidence foundations shipped)
 
-These priorities are done and kept here for history:
+## Current Focus
 
-- Priority 1 — Stronger State Verification
-- Priority 2 — Richer Element Identity
+- Wait and Synchronization Reliability
+- Actionability Resolution
+
+## Upcoming Work
 
-Completion notes:
+- Adjustable Control Support
+- Signal-Oriented Diagnostic Filtering
+- Long Press Gesture
+- Better Compose / Custom Control Semantics
 
-- State-aware verification is now implemented and wired through the tool surface.
-- Platform-native element metadata and selector-confidence hints are now part of the runtime contract.
+## Later Horizon
+
+- Pinch to Zoom
+- Action Trace Correlation
 
 ---
 
-# Priority 1 — Stronger State Verification
+# Stronger State Verification
 
-## Why first
+## Rationale
 Highest leverage improvement.
 
 **Status:** Completed
@@ -52,7 +76,7 @@ Most failures are not “can’t act,” they’re:
 - weak verification
 - retry loops caused by inference
 
-## Deliver
+## Scope
 - Direct readable control values
 - Expanded `expect_*` verification
 - Move from inference to state introspection
@@ -60,7 +84,7 @@ Most failures are not “can’t act,” they’re:
 ## Expected Impact
 Very high.
 
-## Done Criteria
+## Exit Criteria
 - Control state readable for core widgets (toggle, slider, input, dropdown)
 - New expect_* state verifiers implemented
 - Agents can verify state without visual inference in representative flows
@@ -73,15 +97,15 @@ Very high.
 
 ## Dependencies
 Blocks or strengthens:
-- Priority 5 — Better Compose / Custom Control Semantics
-- Priority 6 — Pinch to Zoom verification
-- Priority 7 — Action Trace Correlation
+- Better Compose / Custom Control Semantics
+- Pinch to Zoom
+- Action Trace Correlation
 
 ---
 
-# Priority 2 — Richer Element Identity
+# Richer Element Identity
 
-## Why second
+## Rationale
 Directly reduces selector brittleness.
 
 **Status:** Completed
@@ -91,7 +115,7 @@ Improves:
 - repeatability
 - agent confidence
 
-## Deliver
+## Scope
 - Stable IDs / test tags prioritization
 - Selector confidence metadata
 - Preferred selector hierarchy
@@ -99,7 +123,7 @@ Improves:
 ## Expected Impact
 Very high.
 
-## Done Criteria
+## Exit Criteria
 - Stable selector preference order implemented
 - Test tags/resource IDs surfaced where available
 - Selector confidence metadata available
@@ -112,24 +136,26 @@ Very high.
 
 ## Dependencies
 Blocks or strengthens:
-- Priority 4 — Long Press targeting reliability
-- Priority 5 — Better Compose / Custom Control Semantics
-- Priority 6 — Pinch to Zoom targeting
+- Long Press Gesture
+- Better Compose / Custom Control Semantics
+- Pinch to Zoom
 
 ---
 
-# Priority 3 — Wait and Synchronization Reliability
+# Wait and Synchronization Reliability
 
-## Why third
+## Rationale
 Reliable async synchronization is foundational for agent success and should precede gesture expansion.
 
+**Status:** Spec Ready
+
 Addresses failures where agents:
 - skip UI waits after actions
 - rely on network/log signals too early
 - struggle with in-place UI updates
 - misread stale UI snapshots
 
-## Deliver
+## Scope
 - UI-first synchronization policy guidance
 - wait_for_ui_change (hierarchy diff based waiting)
 - Structured loading state detection
@@ -139,7 +165,7 @@ Addresses failures where agents:
 ## Expected Impact
 Very high.
 
-## Done Criteria
+## Exit Criteria
 - wait_for_ui_change implemented
 - Loading state detection available for representative controls
 - Snapshot revision or staleness metadata exposed
@@ -154,20 +180,159 @@ Very high.
 
 ## Dependencies
 Depends on:
-- Priority 1 — Stronger State Verification
-- Priority 2 — Richer Element Identity
+- Stronger State Verification
+- Richer Element Identity
+
+Blocks or strengthens:
+- Better Compose / Custom Control Semantics
+- Action Trace Correlation
+
+---
+
+# Actionability Resolution
+
+## Rationale
+Reduces failures caused by interacting with discoverable but non-actionable UI nodes.
+
+**Status:** Planned
+
+Addresses cases where:
+- visible text is not the true click target
+- child nodes differ from actionable containers
+- affordance exists but handler ownership is ambiguous
+
+## Scope
+- Actionable container resolution
+- Executable-target preference rules
+- Actionability confidence metadata
+- Post-action state verification integration
+
+## Expected Impact
+High.
+
+## Exit Criteria
+- Actionable target resolution implemented
+- Preference rules defined for executable containers over leaf nodes
+- Actionability confidence surfaced
+- Benchmark flows show reduced false taps and submit ambiguity
+
+## Success Metrics
+- Reduced mis-targeted action failures
+- Lower retarget retries
+- Higher first-attempt action success
+
+## Dependencies
+Depends on:
+- Stronger State Verification
+- Richer Element Identity
+- Wait and Synchronization Reliability
+
+Blocks or strengthens:
+- Adjustable Control Support
+- Better Compose / Custom Control Semantics
+
+---
+
+# Adjustable Control Support
+
+## Rationale
+High leverage improvement for sliders and parameterized controls.
+
+**Status:** Planned
+
+Addresses friction around:
+- coordinate-calibrated slider interaction
+- snapping and quantized controls
+- weak state confirmation after adjustment
+
+## Scope
+New semantic control support:
+
+```json
+set_slider_value(target, value, tolerance?)
+```
+
+Includes:
+- semantic adjustable control manipulation
+- read-back verification loop
+- tolerance-aware value setting
+- fallback coordinate calibration only when needed
+
+## Expected Impact
+High.
+
+## Exit Criteria
+- Adjustable control primitive implemented
+- Verification loop reads and confirms resulting values
+- Tolerance model defined
+- Benchmark slider/custom control flows validated
+
+## Success Metrics
+- Higher custom control interaction success rate
+- Fewer retries adjusting controls
+- Reduced coordinate-guessing failures
+
+## Dependencies
+Depends on:
+- Stronger State Verification
+- Richer Element Identity
+- Actionability Resolution
 
 Blocks or strengthens:
-- Priority 5 — Better Compose / Custom Control Semantics
-- Priority 7 — Action Trace Correlation
+- Better Compose / Custom Control Semantics
+- Pinch to Zoom
+
+---
+
+# Signal-Oriented Diagnostic Filtering
+
+## Rationale
+Improves observability by separating causal signals from diagnostic noise.
+
+**Status:** Planned
+
+Addresses friction from:
+- noisy log streams
+- weak signal extraction
+- difficult action-to-signal attribution
+
+## Scope
+- Structured diagnostic classification
+- Noise filtering heuristics
+- Signal relevance scoring
+- App vs system event tagging
+
+## Expected Impact
+High.
+
+## Exit Criteria
+- Diagnostic signal classification model defined
+- Noise filtering available in representative flows
+- Relevant action-linked signals surfaced separately from background noise
+- Debug workflows validated with filtered signals
+
+## Success Metrics
+- Lower time-to-root-cause
+- Faster identification of relevant action signals
+- Reduced diagnostic ambiguity
+
+## Dependencies
+Depends on:
+- Stronger State Verification
+- Wait and Synchronization Reliability
+
+Strengthens:
+- Action Trace Correlation
 
 ---
 
-# Priority 4 — Long Press Gesture
+# Long Press Gesture
 
-## Why fourth
+## Rationale
 High utility, relatively low complexity.
 
+**Status:** Planned
+
 Unlocks many currently awkward interactions:
 
 - context menus
@@ -177,7 +342,7 @@ Unlocks many currently awkward interactions:
 
 Broad usefulness.
 
-## Deliver
+## Scope
 New tool:
 
 ```json
@@ -191,7 +356,7 @@ Verification alignment:
 ## Expected Impact
 High.
 
-## Done Criteria
+## Exit Criteria
 - long_press tool implemented across supported platforms
 - Duration defaults and overrides supported
 - Verification patterns for long press outcomes defined
@@ -204,25 +369,28 @@ High.
 
 ## Dependencies
 Depends on:
-- Priority 2 — Richer Element Identity
+- Richer Element Identity
 
 Strengthens:
-- Priority 5 semantics interaction contracts
+- Better Compose / Custom Control Semantics
 
 ---
 
-# Priority 5 — Better Compose / Custom Control Semantics
+# Better Compose / Custom Control Semantics
+
+## Rationale
+Important, but strengthened by earlier capabilities first.
 
-## Why fifth
-Important, but strengthened by priorities 1–4 first.
+**Status:** Planned
 
 Semantics become more useful once:
 - identity is stronger
 - verification is stronger
 - gestures are richer
 - synchronization is more reliable
+- action execution is more precise
 
-## Deliver
+## Scope
 - Composite control traits
 - Control role enrichment (adjustable, expandable, selectable_group)
 - Interaction contracts metadata
@@ -233,7 +401,7 @@ Semantics become more useful once:
 ## Expected Impact
 High.
 
-## Done Criteria
+## Exit Criteria
 - Semantic traits implemented for major custom control classes
 - Interaction contracts surfaced in snapshot model
 - Confidence model defined for derived semantics
@@ -246,18 +414,23 @@ High.
 
 ## Dependencies
 Depends on:
-- Priority 1 — Stronger State Verification
-- Priority 2 — Richer Element Identity
-- Priority 3 — Wait and Synchronization Reliability
-- Priority 4 — Long Press
+- Stronger State Verification
+- Richer Element Identity
+- Wait and Synchronization Reliability
+- Actionability Resolution
+- Adjustable Control Support
+- Signal-Oriented Diagnostic Filtering
+- Long Press Gesture
 
 ---
 
-# Priority 6 — Pinch to Zoom
+# Pinch to Zoom
 
-## Why sixth
+## Rationale
 Valuable, but narrower than long press.
 
+**Status:** Planned
+
 Applies mainly to:
 - maps
 - images
@@ -266,7 +439,7 @@ Applies mainly to:
 
 Useful, but less universal.
 
-## Deliver
+## Scope
 
 ```json
 pinch_to_zoom(target, scale, center?)
@@ -279,7 +452,7 @@ Verification:
 ## Expected Impact
 Medium-high.
 
-## Done Criteria
+## Exit Criteria
 - pinch_to_zoom implemented
 - Zoom in/out flows supported
 - Verification primitives for viewport or zoom state available
@@ -292,27 +465,29 @@ Medium-high.
 
 ## Dependencies
 Depends on:
-- Priority 1 — Stronger State Verification
-- Priority 2 — Richer Element Identity
+- Stronger State Verification
+- Richer Element Identity
 
 ---
 
-# Priority 7 — Action Trace Correlation
+# Action Trace Correlation
 
-## Why seventh
+## Rationale
 Very valuable for debugging,
 but less critical than improving control success first.
 
+**Status:** Planned
+
 Improves diagnosis more than task completion.
 
-## Deliver
+## Scope
 - Action correlation metadata
 - UI/network/log linkage
 
 ## Expected Impact
 Medium-high.
 
-## Done Criteria
+## Exit Criteria
 - Action correlation model defined
 - UI/network/log linkage captured for representative actions
 - Correlation metadata exposed to agents
@@ -325,79 +500,97 @@ Medium-high.
 
 ## Dependencies
 Depends on:
-- Priority 1 — Stronger State Verification
-- Priority 2 — Richer Element Identity
-- Priority 3 — Wait and Synchronization Reliability
+- Stronger State Verification
+- Richer Element Identity
+- Wait and Synchronization Reliability
 
 ---
 
-# Delivery Waves
+# Roadmap Sequence
 
 ## Dependency Summary
-Foundational sequence:
 
-Layer 1 (Foundations)
-- Priority 1
-- Priority 2
+Foundation
+- Stronger State Verification
+- Richer Element Identity
+
+Synchronization & Actionability
+- Wait and Synchronization Reliability
+- Actionability Resolution
 
-Layer 2 (Synchronization)
-- Priority 3 depends on 1,2
+Control Precision & Observability
+- Adjustable Control Support
+- Signal-Oriented Diagnostic Filtering
 
-Layer 3 (Interaction Expansion)
-- Priority 4 depends on 2
-- Priority 5 depends on 1,2,3,4
-- Priority 6 depends on 1,2
+Interaction Expansion
+- Long Press Gesture
+- Better Compose / Custom Control Semantics
+- Pinch to Zoom
 
-Layer 4 (Observability)
-- Priority 7 depends on 1,2,3
+Deep Observability
+- Action Trace Correlation
 
-## Wave 1 (Immediate)
+## Wave 1 (Current Focus)
 - Stronger State Verification
 - Richer Element Identity
 - Wait and Synchronization Reliability
+- Actionability Resolution
 
 Focus:
 Make core loop more reliable.
 
 ---
 
-## Wave 2
-- Long Press
-- Better Compose Semantics
+## Wave 2 (Control Precision + Diagnostics)
+- Adjustable Control Support
+- Signal-Oriented Diagnostic Filtering
+
+Focus:
+Improve control precision and signal observability.
+
+---
+
+## Wave 3 (Interaction Expansion)
+- Long Press Gesture
+- Better Compose / Custom Control Semantics
 
 Focus:
 Expand interaction capability.
 
 ---
 
-## Wave 3
+## Wave 4 (Advanced Gestures + Deep Observability)
 - Pinch to Zoom
 - Action Trace Correlation
 
 Focus:
-Advanced gestures + observability.
+Advanced gestures + deep observability.
 
 ---
 
-# Priority Stack Summary
+# Roadmap Ordering
 
-Execution Order:
+Roadmap Ordering:
 1. Stronger State Verification
 2. Richer Element Identity
 3. Wait and Synchronization Reliability
-4. Long Press
-5. Better Compose / Custom Control Semantics
-6. Pinch to Zoom
-7. Action Trace Correlation
+4. Actionability Resolution
+5. Adjustable Control Support
+6. Signal-Oriented Diagnostic Filtering
+7. Long Press Gesture
+8. Better Compose / Custom Control Semantics
+9. Pinch to Zoom
+10. Action Trace Correlation
 
 Rationale:
-- Priorities 1–3 harden control, verification, and synchronization.
-- Priorities 4–6 expand interaction capability.
-- Priority 7 adds observability once control reliability matures.
+- Early roadmap items harden state, targeting, synchronization, action execution.
+- Mid roadmap items improve control precision and signal observability.
+- Later interaction-focused items expand interaction coverage.
+- Final observability work deepens debugging observability.
 
 ---
 
-## Explicitly Deferred
+## Future Considerations
 Still out of scope:
 
 - Recovery planning logic