mobile-debug-mcp 0.29.0 → 0.30.1

package/dist/observe/snapshot-metadata.js

@@ -30,6 +30,58 @@ function stableElementSignature(element) {
         bounds: normalizeBounds(element.bounds)
     };
 }
+function stableElementIdentity(element, index) {
+    const stableId = normalize(element.stable_id);
+    if (stableId)
+        return `stable:${stableId}`;
+    return `fallback:${crypto.createHash('sha1').update(JSON.stringify({
+        text: normalize(element.text),
+        contentDescription: normalize(element.contentDescription),
+        resourceId: normalize(element.resourceId),
+        type: normalize(element.type),
+        bounds: normalizeBounds(element.bounds),
+        index
+    })).digest('hex')}`;
+}
+function buildElementSignatures(tree) {
+    const signatures = new Map();
+    const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+    for (let index = 0; index < elements.length; index++) {
+        const element = elements[index];
+        if (!element)
+            continue;
+        const identity = stableElementIdentity(element, index);
+        signatures.set(identity, crypto.createHash('sha1').update(JSON.stringify(stableElementSignature(element))).digest('hex'));
+    }
+    return signatures;
+}
+function summarizeSnapshotDelta(previous, currentElements) {
+    if (!previous)
+        return null;
+    let added = 0;
+    let removed = 0;
+    let mutated = 0;
+    for (const [identity, signature] of currentElements.entries()) {
+        const previousSignature = previous.elementSignatures.get(identity);
+        if (previousSignature === undefined) {
+            added++;
+        }
+        else if (previousSignature !== signature) {
+            mutated++;
+        }
+    }
+    for (const identity of previous.elementSignatures.keys()) {
+        if (!currentElements.has(identity))
+            removed++;
+    }
+    return {
+        previous_snapshot_revision: previous.revision,
+        added_elements: added,
+        removed_elements: removed,
+        mutated_elements: mutated,
+        total_elements: currentElements.size
+    };
+}
 export function computeSnapshotSignature(tree) {
     if (!tree || tree.error)
         return null;
@@ -67,6 +119,10 @@ export function detectLoadingState(tree, source) {
 export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverride) {
     const signature = signatureOverride ?? computeSnapshotSignature(tree);
     const previous = snapshotStateByDevice.get(deviceKey);
+    const hasValidTree = !!tree && !tree.error;
+    const currentElementSignatures = hasValidTree
+        ? buildElementSignatures(tree)
+        : previous?.elementSignatures ?? new Map();
     let revision = 1;
     if (previous) {
         if (signature === null) {
@@ -76,10 +132,15 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
             revision = previous.signature === signature ? previous.revision : previous.revision + 1;
         }
     }
-    snapshotStateByDevice.set(deviceKey, { revision, signature });
+    snapshotStateByDevice.set(deviceKey, {
+        revision,
+        signature,
+        elementSignatures: currentElementSignatures
+    });
     return {
         snapshot_revision: revision,
         captured_at_ms: Date.now(),
+        snapshot_delta: hasValidTree ? summarizeSnapshotDelta(previous, currentElementSignatures) : null,
         loading_state: detectLoadingState(tree, source)
     };
 }

package/dist/server/tool-definitions.js

@@ -244,7 +244,7 @@ Failure Handling:
     },
     {
         name: 'capture_debug_snapshot',
-        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, and loading_state when detectable.',
+        description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, snapshot_delta, and loading_state when detectable.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -295,7 +295,7 @@ Failure Handling:
     },
     {
         name: 'get_ui_tree',
-        description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata when available.',
+        description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata and incremental delta signals when available.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -376,11 +376,14 @@ Inputs:
 - expected_change (optional): hierarchy_diff, text_change, or state_change
 - timeout_ms (optional)
 - stability_window_ms (optional)
+- scope (optional): screen or subtree
+- target (optional): element_id when scope=subtree
 
 Guidance:
 - Prefer wait_for_screen_change for navigation transitions.
 - Prefer wait_for_ui_change for in-place mutations and non-navigation updates.
 - Use the returned snapshot_revision as the observed synchronization point when available.
+- Scoped waits return scope-aware stability metadata and a lightweight change summary.
 
 Failure Handling:
 - TIMEOUT means the UI did not change in a stable way within the allotted time.`,
@@ -390,8 +393,10 @@ Failure Handling:
                 platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
                 deviceId: { type: 'string', description: 'Optional device id/udid to target' },
                 expected_change: { type: 'string', enum: ['hierarchy_diff', 'text_change', 'state_change'], description: 'Optional type of UI change to wait for' },
+                scope: { type: 'string', enum: ['screen', 'subtree'], default: 'screen', description: 'Synchronization scope for the wait' },
+                target: { type: 'string', description: 'Target element_id when scope is subtree' },
                 timeout_ms: { type: 'number', description: 'Timeout in ms to wait for change (default 60000)', default: 60000 },
-                stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 250)', default: 250 }
+                stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 300)', default: 300 }
             }
         }
     },

package/dist/server/tool-handlers.js

@@ -266,9 +266,11 @@ async function handleWaitForUIChange(args) {
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
     const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
-    const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 250;
+    const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 300;
     const expected_change = getStringArg(args, 'expected_change');
-    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change });
+    const scope = getStringArg(args, 'scope');
+    const target = getStringArg(args, 'target');
+    const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change, scope, target });
     return wrapResponse(res);
 }
 async function handleFindElement(args) {

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.29.0'
+    version: '0.30.1'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/docs/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.30.1]
+- Synced the server-reported version in `src/server-core.ts` with `package.json` so contract checks pass.
+- Completed the RFC 013 wait/synchronization implementation, including scoped waits and freshness metadata.
+- Completed the RFC 014 actionability implementation for taps and adjustable controls.
+- Added regression coverage for subtree collection, scoped waits, snapshot deltas, and stale actionability checks.
+
+## [0.30.0]
+- Folded RFC 013 synchronization semantics into the main spec and aligned the interact docs with the shipped `wait_for_ui_change` behavior.
+- Updated `wait_for_ui_change` to use a 300ms stabilization default and to reset stabilization on new in-place mutations.
+- Validated the in-place UI mutation flow on the Modul8 emulator app, including a delayed state-change case.
+
 ## [0.29.0]
 - Added empty resource handlers and declared the `resources` capability so Codex MCP discovery can complete the handshake against the published npm package.
 - Moved the startup healthcheck behind an opt-in flag to keep the stdio protocol channel quiet by default.

package/docs/ROADMAP.md

@@ -32,6 +32,7 @@ Track roadmap impact across releases using:
 - Gesture success rate
 - Mean time to root cause during debugging
 - Overall agent task completion rate
+- Reduced sequencing errors in multi-step interaction flows
 
 Primary KPI:
 Higher task success with fewer retries.
@@ -47,10 +48,10 @@ Higher task success with fewer retries.
 - Better Compose / Custom Control Semantics — Complete (Semantic role enrichment and custom-adjustable inference shipped)
 - Verification Stabilization and Temporal Convergence — Complete (Temporal verification and convergence logic shipped)
 - Action Trace and Execution Observability — Complete (Structured execution trace model shipped)
+- Wait and Synchronization Reliability — Complete (RFC 013 folded into the main spec and shipped behavior verified on emulator)
 
 ## Current Focus
 
-- Wait and Synchronization Reliability (implementation + tuning)
 - Actionability Resolution
 - Adjustable Control Precision Hardening
 
@@ -74,13 +75,14 @@ Addresses friction around:
 - environment drift across machines
 - setup failures blocking first use
 
-## Scope
 - Automatic discovery of adb
 - Automatic discovery of xcrun
 - idb detection and guided bootstrap support
 - Startup toolchain validation
 - Environment health diagnostics / doctor-style checks
 - Minimal-manual-configuration defaults
+- Runtime device/emulator health signals (crash detection, process lifecycle awareness)
+- App stability monitoring during active sessions
 
 ## Expected Impact
 High.
@@ -97,6 +99,7 @@ High.
 - Lower environment configuration failures
 - Faster time-to-first-successful-session
 - Reduced support/debugging caused by local setup issues
+- Reduced unknown-failure sessions caused by app or emulator instability
 
 ## Dependencies
 Depends on:
@@ -151,7 +154,7 @@ Very high.
 Blocks or strengthens:
 - Better Compose / Custom Control Semantics
 - Pinch to Zoom
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -212,8 +215,11 @@ Addresses failures where agents:
 - wait_for_ui_change (hierarchy diff based waiting)
 - Structured loading state detection
 - Snapshot revision / staleness metadata
-- Focused snapshot views / incremental snapshot diffs
+- Incremental / diff-based snapshot delivery (token-efficient)
+- Focused snapshot scoping (subtree / target-based)
 - Compose-aware wait robustness improvements
+- Explicit interaction sequencing guidance (tap → wait → verify pattern)
+- Exploration of optional action-level synchronization ergonomics (e.g. implicit stabilization or wait flags)
 
 ## Expected Impact
 Very high.
@@ -231,6 +237,8 @@ Very high.
 - Fewer retries caused by premature actions
 - Higher wait success rate for dynamic UI flows
 - Lower fallback usage to network/log checks
+- Reduced need for manual sequencing by agents in stateful flows
+- Reduced average snapshot size (tokens)
 
 ## Dependencies
 Depends on:
@@ -239,7 +247,7 @@ Depends on:
 
 Blocks or strengthens:
 - Better Compose / Custom Control Semantics
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -307,6 +315,7 @@ Addresses cases where:
 - Executable-target preference rules
 - Actionability confidence metadata
 - Post-action state verification integration
+- Geometry-aware fallback targeting for weak semantic surfaces (e.g. sliders without accessible nodes)
 
 ## Expected Impact
 High.
@@ -321,6 +330,7 @@ High.
 - Reduced mis-targeted action failures
 - Lower retarget retries
 - Higher first-attempt action success
+- Reduced need for empirical coordinate probing on custom controls
 
 ## Dependencies
 Depends on:
@@ -403,6 +413,7 @@ Addresses friction around:
 - Drag vs tap adjustment strategy heuristics
 - Improved value snapping convergence
 - Control-specific adjustment fallback policies
+- Controlled search strategies for value convergence (e.g. binary / progressive adjustment)
 
 ## Expected Impact
 High.
@@ -465,7 +476,7 @@ Depends on:
 - Wait and Synchronization Reliability
 
 Strengthens:
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -675,7 +686,7 @@ Interaction Expansion
 - Pinch to Zoom
 
 Deep Observability
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ## Wave 1 (Current Focus)
 - Stronger State Verification