mobile-debug-mcp 0.29.0 → 0.30.1

package/AGENTS.md

@@ -75,3 +75,16 @@ For test authoring details, rely on the `test-authoring` skill package rather th
 ## Notes for maintainers
 
 This file is intentionally short. Keep task-specific guidance in `skills/...` so multiple agent systems can reuse the same instructions.
+
+## Testing
+
+- `npm run test:unit` runs every automated unit test under `test/unit/...`
+- `npm run test:device` runs the automated device smoke checks under `test/device/automated/...`
+- `npm run verify` runs the default maintainer verification sequence: lint, build, and unit tests
+- Manual and debug-oriented device scripts live under `test/device/manual/...` and are not part of the default test commands
+
+## Utility Scripts
+
+- `npm run healthcheck` runs the `idb`/tooling healthcheck helper from `src/utils/cli/idb/check-idb.ts`
+- `npm run install-idb` runs the guided `idb` installer helper from `src/utils/cli/idb/install-idb.ts`
+- `npm run preflight-ios` runs the iOS preflight helper from `src/utils/cli/ios/preflight-ios.ts`

package/README.md

@@ -16,7 +16,11 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
 - Xcode command-line tools for iOS support
 - [idb](https://github.com/facebook/idb) for iOS device support
 
-## Configuration example
+## Configuration
+
+<details>
+
+<summary>Android Studio</summary>
 
 ```json
 {
@@ -29,7 +33,45 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
   }
 }
 ```
-You will need to add ADB_PATH for Android and XCRUN_PATH and IDB_PATH for iOS.
+
+</details>
+
+<details>
+
+<summary>Copilot</summary>
+
+```json
+{
+  "mcpServers": {
+    "mobile-debug": {
+      "command": "npx",
+      "args": ["--yes","mobile-debug-mcp","server"],
+      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun", "IDB_PATH": "/path/to/idb" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+
+<summary>Codex</summary>
+
+Use STDIO
+
+command: npx
+
+args: 
+* --yes
+* mobile-debug-mcp
+
+environment variables:
+* ADB_PATH: /path/to/adb
+* XCRUN_PATH: /usr/bin/xcrun
+* IDC_PATH: /path/to/idb"
+
+</details>
 
 ## Usage
 
@@ -48,25 +90,6 @@ Feature building:
 - Agents: [AGENTS.md](AGENTS.md) — cold-start guidance for autonomous agents entering the public repo
 - Skills: [skills/README.md](skills/README.md) — portable Markdown skill packages for agents such as Copilot, Codex, Claude, or custom systems
 
-## Testing
-
-- `npm run test:unit` runs every automated unit test under `test/unit/...`
-- `npm run test:device` runs the automated device smoke checks under `test/device/automated/...`
-- `npm run verify` runs the default maintainer verification sequence: lint, build, and unit tests
-- Manual and debug-oriented device scripts live under `test/device/manual/...` and are not part of the default test commands
-
-## Utility Scripts
-
-- `npm run healthcheck` runs the `idb`/tooling healthcheck helper from `src/utils/cli/idb/check-idb.ts`
-- `npm run install-idb` runs the guided `idb` installer helper from `src/utils/cli/idb/install-idb.ts`
-- `npm run preflight-ios` runs the iOS preflight helper from `src/utils/cli/ios/preflight-ios.ts`
-
-## Agent skills
-
-- `skills/mcp-builder/` contains reusable build/install guidance for agents
-- `skills/test-authoring/` contains reusable test-creation guidance aligned to this repo's current test structure
-- Skills are written as plain Markdown packages so they can be consumed by different agent systems rather than one vendor-specific runtime
-
 ## License
 
 MIT

package/dist/interact/index.js

@@ -95,10 +95,68 @@ export class ToolsInteract {
         }
         return null;
     }
+    static _resolveParentIndex(elements, parentId) {
+        if (parentId === undefined || parentId === null)
+            return null;
+        if (typeof parentId === 'number' && Number.isInteger(parentId) && parentId >= 0 && parentId < elements.length) {
+            return parentId;
+        }
+        if (typeof parentId === 'string') {
+            const normalized = ToolsInteract._normalize(parentId);
+            if (!normalized)
+                return null;
+            if (/^\d+$/.test(normalized)) {
+                const index = Number(normalized);
+                if (index >= 0 && index < elements.length)
+                    return index;
+            }
+            const foundIndex = elements.findIndex((el) => {
+                if (!el)
+                    return false;
+                return ToolsInteract._normalize(el.resourceId ?? el.resourceID ?? el.id ?? '') === normalized ||
+                    ToolsInteract._normalize(el.stable_id ?? '') === normalized;
+            });
+            return foundIndex >= 0 ? foundIndex : null;
+        }
+        return null;
+    }
     static _isVisibleElement(el) {
         const bounds = ToolsInteract._normalizeBounds(el.bounds);
         return !!el.visible && !!bounds && bounds[2] > bounds[0] && bounds[3] > bounds[1];
     }
+    static _isTapActionable(el, storedStableId, platform) {
+        if (!ToolsInteract._isVisibleElement(el)) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not visible' };
+        }
+        if (el.enabled === false) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is disabled' };
+        }
+        const semanticTapActionable = !!el.semantic && (el.semantic.is_clickable ||
+            (Array.isArray(el.semantic.supported_actions) && el.semantic.supported_actions.some((action) => ToolsInteract._normalize(action) === 'tap')));
+        if (!el.clickable && !(platform === 'ios' && semanticTapActionable)) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not clickable' };
+        }
+        if (storedStableId) {
+            if (!el.stable_id || el.stable_id !== storedStableId) {
+                return { actionable: false, failureCode: 'STALE_REFERENCE', reason: 'element stable_id changed' };
+            }
+        }
+        return { actionable: true };
+    }
+    static _isAdjustableActionable(el, storedStableId) {
+        if (!ToolsInteract._isVisibleElement(el)) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is not visible' };
+        }
+        if (el.enabled === false) {
+            return { actionable: false, failureCode: 'ELEMENT_NOT_INTERACTABLE', reason: 'element is disabled' };
+        }
+        if (storedStableId) {
+            if (!el.stable_id || el.stable_id !== storedStableId) {
+                return { actionable: false, failureCode: 'STALE_REFERENCE', reason: 'element stable_id changed' };
+            }
+        }
+        return { actionable: true };
+    }
     static _computeElementId(platform, deviceId, el, index) {
         const identity = {
             platform,
@@ -120,7 +178,8 @@ export class ToolsInteract {
             platform,
             deviceId,
             bounds,
-            index
+            index,
+            stable_id: el.stable_id ?? null
         });
         return {
             text: el.text ?? null,
@@ -138,6 +197,214 @@ export class ToolsInteract {
             semantic: el.semantic ?? null
         };
     }
+    static _resolveUiChangeScope(tree, scope, target) {
+        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+        const normalizedScope = scope === 'subtree' ? 'subtree' : 'screen';
+        if (normalizedScope === 'screen') {
+            return {
+                elements,
+                resolution: {
+                    scope: 'screen',
+                    target: null,
+                    resolved: true,
+                    resolvedIndex: null,
+                    resolvedStableId: null,
+                    reason: 'screen scope'
+                }
+            };
+        }
+        const requestedTarget = typeof target === 'string' && target.trim().length > 0 ? target.trim() : null;
+        if (!requestedTarget) {
+            return {
+                elements: [],
+                resolution: {
+                    scope: 'subtree',
+                    target: null,
+                    resolved: false,
+                    resolvedIndex: null,
+                    resolvedStableId: null,
+                    reason: 'subtree scope requires a target element id'
+                },
+                error: {
+                    code: 'INVALID_SCOPE',
+                    message: 'scope=subtree requires a target element_id'
+                }
+            };
+        }
+        const resolved = ToolsInteract._findScopedElement(tree, requestedTarget);
+        if (!resolved) {
+            return {
+                elements: [],
+                resolution: {
+                    scope: 'subtree',
+                    target: requestedTarget,
+                    resolved: false,
+                    resolvedIndex: null,
+                    resolvedStableId: null,
+                    reason: 'target element could not be resolved'
+                },
+                error: {
+                    code: 'ELEMENT_NOT_FOUND',
+                    message: `Target element ${requestedTarget} could not be resolved for subtree scope`
+                }
+            };
+        }
+        const subtreeIndices = ToolsInteract._collectSubtreeIndices(elements, resolved.index);
+        const scopedElements = subtreeIndices.map((index) => elements[index]).filter((element) => !!element);
+        return {
+            elements: scopedElements,
+            resolution: {
+                scope: 'subtree',
+                target: requestedTarget,
+                resolved: true,
+                resolvedIndex: resolved.index,
+                resolvedStableId: resolved.stableId,
+                reason: resolved.reason
+            }
+        };
+    }
+    static _findScopedElement(tree, targetElementId) {
+        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+        const platform = tree?.device?.platform === 'ios' ? 'ios' : 'android';
+        const deviceId = tree?.device?.id ?? undefined;
+        const normalizedTarget = ToolsInteract._normalize(targetElementId);
+        for (let i = 0; i < elements.length; i++) {
+            const el = elements[i];
+            if (!el)
+                continue;
+            const computedElementId = ToolsInteract._computeElementId(platform, deviceId, el, i);
+            if (computedElementId === targetElementId) {
+                return {
+                    index: i,
+                    stableId: el.stable_id ?? null,
+                    reason: 'element_id_match'
+                };
+            }
+        }
+        for (let i = 0; i < elements.length; i++) {
+            const el = elements[i];
+            if (!el)
+                continue;
+            if (el.stable_id && ToolsInteract._normalize(el.stable_id) === normalizedTarget) {
+                return {
+                    index: i,
+                    stableId: el.stable_id,
+                    reason: 'stable_id_match'
+                };
+            }
+        }
+        const storedContext = ToolsInteract._resolvedUiElements.get(targetElementId);
+        if (storedContext?.stable_id) {
+            const normalizedStoredStableId = ToolsInteract._normalize(storedContext.stable_id);
+            for (let i = 0; i < elements.length; i++) {
+                const el = elements[i];
+                if (!el?.stable_id)
+                    continue;
+                if (ToolsInteract._normalize(el.stable_id) === normalizedStoredStableId) {
+                    return {
+                        index: i,
+                        stableId: el.stable_id,
+                        reason: 'stored_stable_id_match'
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    static _collectSubtreeIndices(elements, rootIndex) {
+        if (!Array.isArray(elements) || rootIndex < 0 || rootIndex >= elements.length)
+            return [];
+        const visited = new Set();
+        const stack = [rootIndex];
+        const result = [];
+        while (stack.length > 0) {
+            const index = stack.pop();
+            if (index === undefined || visited.has(index) || index < 0 || index >= elements.length)
+                continue;
+            visited.add(index);
+            result.push(index);
+            const element = elements[index];
+            if (!element)
+                continue;
+            const directChildren = new Set();
+            if (Array.isArray(element.children)) {
+                for (const childIndex of element.children) {
+                    if (typeof childIndex === 'number' && Number.isInteger(childIndex) && childIndex >= 0 && childIndex < elements.length) {
+                        directChildren.add(childIndex);
+                    }
+                }
+            }
+            for (let i = 0; i < elements.length; i++) {
+                if (ToolsInteract._resolveParentIndex(elements, elements[i]?.parentId) === index) {
+                    directChildren.add(i);
+                }
+            }
+            for (const childIndex of directChildren) {
+                if (!visited.has(childIndex))
+                    stack.push(childIndex);
+            }
+        }
+        return result.sort((left, right) => left - right);
+    }
+    static _changeIdentityForElement(el, index) {
+        const stableId = ToolsInteract._normalize(el.stable_id);
+        if (stableId)
+            return `stable:${stableId}`;
+        return `fallback:${ToolsInteract._hash({
+            text: ToolsInteract._normalize(el.text ?? el.label ?? el.value ?? ''),
+            contentDescription: ToolsInteract._normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? ''),
+            resourceId: ToolsInteract._normalize(el.resourceId ?? el.resourceID ?? el.id ?? ''),
+            type: ToolsInteract._normalize(el.type ?? el.class ?? ''),
+            bounds: ToolsInteract._normalizeBounds(el.bounds) ?? [0, 0, 0, 0],
+            index
+        })}`;
+    }
+    static _summarizeUiChangeDelta(initialElements, currentElements) {
+        const buildMap = (elements) => {
+            const map = new Map();
+            for (let i = 0; i < elements.length; i++) {
+                const element = elements[i];
+                if (!element)
+                    continue;
+                const key = ToolsInteract._changeIdentityForElement(element, i);
+                map.set(key, ToolsInteract._hash({
+                    text: ToolsInteract._normalize(element.text ?? element.label ?? element.value ?? ''),
+                    contentDescription: ToolsInteract._normalize(element.contentDescription ?? element.contentDesc ?? element.accessibilityLabel ?? ''),
+                    resourceId: ToolsInteract._normalize(element.resourceId ?? element.resourceID ?? element.id ?? ''),
+                    type: ToolsInteract._normalize(element.type ?? element.class ?? ''),
+                    bounds: ToolsInteract._normalizeBounds(element.bounds) ?? [0, 0, 0, 0],
+                    state: element.state ?? null,
+                    visible: !!element.visible,
+                    enabled: !!element.enabled,
+                    clickable: !!element.clickable
+                }));
+            }
+            return map;
+        };
+        const initialMap = buildMap(initialElements);
+        const currentMap = buildMap(currentElements);
+        let added = 0;
+        let removed = 0;
+        let mutated = 0;
+        for (const [key, value] of currentMap.entries()) {
+            if (!initialMap.has(key)) {
+                added++;
+            }
+            else if (initialMap.get(key) !== value) {
+                mutated++;
+            }
+        }
+        for (const key of initialMap.keys()) {
+            if (!currentMap.has(key))
+                removed++;
+        }
+        return {
+            total_elements: currentElements.length,
+            added_elements: added,
+            removed_elements: removed,
+            mutated_elements: mutated
+        };
+    }
     static _rememberResolvedElement(elementId, context) {
         if (ToolsInteract._resolvedUiElements.has(elementId)) {
             ToolsInteract._resolvedUiElements.delete(elementId);
@@ -205,6 +472,9 @@ export class ToolsInteract {
         }
         return null;
     }
+    static _uiChangeSignaturesEqual(left, right) {
+        return left.hierarchy === right.hierarchy && left.text === right.text && left.state === right.state;
+    }
     static _resolvedTargetFromElement(elementId, element, index) {
         return {
             elementId,
@@ -381,25 +651,12 @@ export class ToolsInteract {
         let current = chosen;
         let safety = 0;
         while (safety < 20 && current.el && !(current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el)) && current.el.parentId !== undefined && current.el.parentId !== null) {
-            const parentId = current.el.parentId;
-            let parentIndex = null;
-            if (typeof parentId === 'number')
-                parentIndex = parentId;
-            else if (typeof parentId === 'string' && /^\d+$/.test(parentId))
-                parentIndex = Number(parentId);
+            const parentIndex = ToolsInteract._resolveParentIndex(elements, current.el.parentId);
             if (parentIndex !== null && elements[parentIndex]) {
                 current = { el: elements[parentIndex], idx: parentIndex };
                 if (current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el))
                     return current;
             }
-            else if (typeof parentId === 'string') {
-                const foundIndex = elements.findIndex((el) => el.resourceId === parentId || el.id === parentId);
-                if (foundIndex === -1)
-                    break;
-                current = { el: elements[foundIndex], idx: foundIndex };
-                if (current.el.clickable || current.el.focusable || ToolsInteract._isSemanticActionable(current.el))
-                    return current;
-            }
             else {
                 break;
             }
@@ -513,11 +770,9 @@ export class ToolsInteract {
             return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, fingerprintBefore);
         }
         const resolvedTarget = ToolsInteract._resolvedTargetFromElement(resolved.elementId, currentMatch.el, currentMatch.index);
-        if (!ToolsInteract._isVisibleElement(currentMatch.el)) {
-            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
-        }
-        if (currentMatch.el.enabled === false) {
-            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
+        const tapActionability = ToolsInteract._isTapActionable(currentMatch.el, resolved.stable_id, resolved.platform);
+        if (!tapActionability.actionable) {
+            return ToolsInteract._actionFailure(actionType, selector, resolvedTarget, tapActionability.failureCode ?? 'ELEMENT_NOT_INTERACTABLE', true, fingerprintBefore);
         }
         const bounds = ToolsInteract._normalizeBounds(currentMatch.el.bounds) ?? resolved.bounds;
         if (!bounds || bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
@@ -550,6 +805,7 @@ export class ToolsInteract {
         const sourcePlatform = platform || 'android';
         let resolvedPlatform = sourcePlatform;
         let resolvedDeviceId = deviceId;
+        const storedResolvedTarget = element_id ? ToolsInteract._resolvedUiElements.get(element_id) ?? null : null;
         const fingerprintBefore = await ToolsInteract._captureFingerprint(resolvedPlatform, resolvedDeviceId);
         let semanticFallbackElement = null;
         const traceSteps = [];
@@ -755,6 +1011,10 @@ export class ToolsInteract {
             resolvedTarget = resolved.resolvedTarget;
             const currentEl = resolved.match.el;
             cachedResolvedMatch = resolved.match;
+            const adjustableActionability = ToolsInteract._isAdjustableActionable(currentEl, storedResolvedTarget?.stable_id);
+            if (!adjustableActionability.actionable) {
+                return buildFailure(adjustableActionability.failureCode ?? 'ELEMENT_NOT_INTERACTABLE', adjustableActionability.reason ?? 'adjustable control is not actionable', resolvedTarget, currentDevice, lastObservedState, attemptCount, lastAdjustmentMode, true);
+            }
             const bounds = ToolsInteract._normalizeBounds(currentEl.bounds);
             const valueRange = currentEl.state?.value_range ?? null;
             const currentValue = ToolsInteract._readNumericControlValue(currentEl, property);
@@ -1708,49 +1968,97 @@ export class ToolsInteract {
             }
         };
     }
-    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 250, expected_change }) {
+    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change, scope = 'screen', target = null }) {
         const start = Date.now();
         const pollIntervalMs = 300;
-        const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 250);
+        const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300);
         let baseline = null;
+        let baselineScope = null;
         let lastObservedRevision = null;
         let lastLoadingState = null;
+        let lastSnapshotFreshnessMs = null;
+        let candidateSignatures = null;
+        let candidateObservedChange = null;
+        let candidateSinceMs = null;
+        let lastChangeSummary = null;
+        let lastScopeResolution = {
+            scope: scope === 'subtree' ? 'subtree' : 'screen',
+            target: target && typeof target === 'string' ? target : null,
+            resolved: scope !== 'subtree',
+            resolvedIndex: null,
+            resolvedStableId: null,
+            reason: scope === 'subtree' ? 'target not resolved yet' : 'screen scope'
+        };
         while (Date.now() - start < timeout_ms) {
             try {
                 const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-                const signatures = ToolsInteract._buildUiChangeSignatures(tree);
+                const scopedTree = ToolsInteract._resolveUiChangeScope(tree, scope, target);
+                if (scopedTree.error) {
+                    lastScopeResolution = scopedTree.resolution;
+                    return {
+                        success: false,
+                        observed_change: null,
+                        snapshot_revision: typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision ?? undefined,
+                        snapshot_freshness_ms: typeof tree?.captured_at_ms === 'number' ? Math.max(0, Date.now() - tree.captured_at_ms) : lastSnapshotFreshnessMs ?? null,
+                        timeout: true,
+                        elapsed_ms: Date.now() - start,
+                        expected_change,
+                        loading_state: tree?.loading_state ?? lastLoadingState ?? null,
+                        scope: scopedTree.resolution.scope,
+                        target: scopedTree.resolution.target,
+                        stability_state: 'transient',
+                        change_summary: lastChangeSummary,
+                        reason: scopedTree.error.message,
+                        error: scopedTree.error
+                    };
+                }
+                const scopedElements = scopedTree.elements;
+                const scopedSignatureTree = {
+                    ...tree,
+                    elements: scopedElements
+                };
+                const signatures = ToolsInteract._buildUiChangeSignatures(scopedSignatureTree);
                 lastObservedRevision = typeof tree?.snapshot_revision === 'number' ? tree.snapshot_revision : lastObservedRevision;
                 lastLoadingState = tree?.loading_state ?? lastLoadingState;
+                lastSnapshotFreshnessMs = typeof tree?.captured_at_ms === 'number' ? Math.max(0, Date.now() - tree.captured_at_ms) : lastSnapshotFreshnessMs;
+                lastChangeSummary = baseline ? ToolsInteract._summarizeUiChangeDelta((baselineScope?.elements ?? []), scopedElements) : lastChangeSummary;
+                lastScopeResolution = scopedTree.resolution;
+                baselineScope = baselineScope ?? scopedTree;
                 if (!baseline) {
                     baseline = signatures;
+                    baselineScope = scopedTree;
                 }
                 else {
                     const observedChange = ToolsInteract._matchesUiChange(expected_change, baseline, signatures);
                     if (observedChange) {
-                        if (stabilityWindow > 0) {
-                            await new Promise(resolve => setTimeout(resolve, stabilityWindow));
-                            const confirmTree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-                            const confirmSignatures = ToolsInteract._buildUiChangeSignatures(confirmTree);
-                            const confirmChange = ToolsInteract._matchesUiChange(expected_change, baseline, confirmSignatures);
-                            if (!confirmChange || confirmSignatures.hierarchy !== signatures.hierarchy || confirmSignatures.text !== signatures.text || confirmSignatures.state !== signatures.state) {
-                                lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision;
-                                lastLoadingState = confirmTree?.loading_state ?? lastLoadingState;
-                                await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
-                                continue;
-                            }
-                            lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision;
-                            lastLoadingState = confirmTree?.loading_state ?? lastLoadingState;
+                        if (!candidateSignatures || !ToolsInteract._uiChangeSignaturesEqual(candidateSignatures, signatures) || candidateObservedChange !== observedChange) {
+                            candidateSignatures = signatures;
+                            candidateObservedChange = observedChange;
+                            candidateSinceMs = Date.now();
                         }
-                        return {
-                            success: true,
-                            observed_change: observedChange,
-                            snapshot_revision: lastObservedRevision ?? undefined,
-                            timeout: false,
-                            elapsed_ms: Date.now() - start,
-                            expected_change,
-                            loading_state: lastLoadingState ?? null,
-                            reason: 'UI change observed'
-                        };
+                        const stableForMs = candidateSinceMs === null ? 0 : Date.now() - candidateSinceMs;
+                        if (stabilityWindow === 0 || stableForMs >= stabilityWindow) {
+                            return {
+                                success: true,
+                                observed_change: candidateObservedChange ?? observedChange,
+                                snapshot_revision: lastObservedRevision ?? undefined,
+                                snapshot_freshness_ms: lastSnapshotFreshnessMs ?? null,
+                                timeout: false,
+                                elapsed_ms: Date.now() - start,
+                                expected_change,
+                                loading_state: lastLoadingState ?? null,
+                                scope: lastScopeResolution.scope,
+                                target: lastScopeResolution.target,
+                                stability_state: 'stable',
+                                change_summary: lastChangeSummary,
+                                reason: 'UI change observed'
+                            };
+                        }
+                    }
+                    else {
+                        candidateSignatures = null;
+                        candidateObservedChange = null;
+                        candidateSinceMs = null;
                     }
                 }
             }
@@ -1763,10 +2071,15 @@ export class ToolsInteract {
             success: false,
             observed_change: null,
             snapshot_revision: lastObservedRevision ?? undefined,
+            snapshot_freshness_ms: lastSnapshotFreshnessMs ?? null,
             timeout: true,
             elapsed_ms: Date.now() - start,
             expected_change,
             loading_state: lastLoadingState ?? null,
+            scope: lastScopeResolution.scope,
+            target: lastScopeResolution.target,
+            stability_state: 'transient',
+            change_summary: lastChangeSummary,
             reason: 'timeout'
         };
     }

package/dist/observe/index.js

@@ -325,6 +325,7 @@ export class ToolsObserve {
         const snapshotMetadata = deriveSnapshotMetadata(snapshotDeviceKey, raw.ui_tree, 'snapshot', raw.ui_tree?.snapshot_revision ? null : (raw.fingerprint || raw.activity || null));
         raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? snapshotMetadata.snapshot_revision;
         raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? snapshotMetadata.captured_at_ms;
+        raw.snapshot_delta = raw.ui_tree?.snapshot_delta ?? snapshotMetadata.snapshot_delta ?? null;
         raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state;
         const semantic = deriveSnapshotSemantic(raw);
         return semantic ? { raw, semantic } : { raw };